Chatbot API Integration: REST API and Signed Webhooks

What the API gives you

The public API lives under /api/v1 and is authenticated with a Bearer API key. These endpoints are live:

• GET and POST /api/v1/chatbots list and create chatbots
• GET and POST /api/v1/chatbots/{id}/sources list and add training sources
• POST /api/v1/chatbots/{id}/chat sends a visitor message and returns the AI reply
• GET /api/v1/conversations lists conversations
• GET /api/v1/leads lists captured leads

Outbound, the webhook action sends a signed POST to a URL you choose whenever it fires, carrying the lead, the transcript, the event type and your workspace id. That is how you get matram.ai data into a CRM, a spreadsheet, or a queue without a native connector.

Before you start

How to use the matram.ai API

Generate a key, make an authenticated call, then wire up a webhook. Every sample below is real and runs against your workspace.

1. 1

   Get on a plan with API access

   The public API requires Standard or Pro. Start the 7-day free trial at matram.ai/signup and pick Standard to unlock it.

2. 2

   Generate an API key

   In the dashboard, open API keys and create one. Copy it once and store it as a secret. Treat it like a password, because it authorises calls against your whole workspace.

3. 3

   Make your first request

   Authenticate with the Authorization header. List your chatbots to confirm the key works:

4. 4

   Send a message programmatically

   Post a visitor message to a specific bot and read the AI reply. This is the endpoint behind a custom chat UI or a server-side automation:

5. 5

   Receive events with a signed webhook

   Add a webhook with your URL and a secret. matram.ai POSTs the event JSON and signs it with HMAC-SHA256 in the x-signature header, so you can verify it is genuine before trusting it.

Authentication, limits and signatures

Authenticate every REST call with a Bearer key over HTTPS. Requests are rate limited to 120 per minute per key. Webhooks are signed so you can verify them. The essentials:

# 1) List chatbots (auth check)
curl https://api.matram.ai/api/v1/chatbots \
  -H "Authorization: Bearer $MATRAM_API_KEY"

# 2) Send a message, get the AI reply
curl -X POST https://api.matram.ai/api/v1/chatbots/BOT_ID/chat \
  -H "Authorization: Bearer $MATRAM_API_KEY" \
  -H "content-type: application/json" \
  -d '{"message":"What are your hours?","visitorId":"abc-123"}'

# 3) Verify a webhook signature (Node)
import { createHmac } from "node:crypto";
const expected =
  "sha256=" + createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (req.headers["x-signature"] !== expected) return res.status(401).end();

Troubleshooting

Cost

The API is included on Standard ($69/mo) and Pro ($199/mo). It is not available on Basic ($29/mo). All plans are flat with unlimited seats, and there is a 7-day free trial with no credit card.

There is no per-call fee on top of your plan. Usage counts against your plan's monthly message allowance in the same way the widget does, and per-key traffic is capped at 120 requests a minute.

Frequently asked questions