Connecting your own systems
An API and webhooks, for a till, a school system or your own app.
API keys
Your own systems (a till, a school or clinic system, your app) can send WhatsApp messages through Sema, keep contacts in step, and check one-time codes. Everything is JSON over HTTPS at /api/v1.
- An owner or admin opens Settings → API keys → + New key.
- Name it for the system that will hold it (“Till at the Ngong Road shop”) and tick only what that system needs.
- Copy the key. It is shown once; Sema keeps only a fingerprint of it, so if it is lost, revoke it and make another.
| Scope | Lets the key |
|---|---|
messages:send | Send messages and batches, and read the balance |
messages:read | Read messages, conversations and the files customers send |
contacts:read | Read contacts |
contacts:write | Add and update contacts |
templates:read | List templates |
templates:write | Write, change and remove templates |
verify | Send and check one-time codes |
webhooks | Add and remove webhooks |
campaigns | List campaigns built in Sema, and start them |
knowledge | Read and keep in step what the AI answers from |
Building with a test key
Every key is live or test, and says which: sema_live_… or sema_test_…. Build with a test key: it checks everything a live key checks and refuses the same mistakes with the same answers, but sends nothing, charges nothing, writes nothing to your workspace and cannot read your real customers. It works before you have connected a number.
Webhooks
Rather than asking Sema what happened, be told. An owner or admin adds an https address in Settings → Webhooks → + New webhook, chooses what it should hear about, and keeps the signing secret, shown once:
| Event | When |
|---|---|
message.received | A customer sends a message |
message.sent | A message we sent left for WhatsApp |
message.delivered | A message we sent was delivered |
message.read | A message we sent was read |
message.failed | A message we sent failed |
contact.opted_out | A customer opts out |
payment.received | A customer pays you by M-Pesa |
template.status_changed | Meta approves, rejects or pauses a template |
deal.created | A deal is added to the pipeline |
deal.stage_changed | A deal moves to another stage |
deal.won | A deal is won |
deal.lost | A deal is lost |
conversation.agent_turn | A customer writes and it is your AI agent’s turn to answer |
appointment.booked | An appointment is booked |
appointment.changed | An appointment is confirmed, moved, cancelled or marked |
Each delivery is signed. Check the signature before trusting it; the reference shows how. Deliveries that fail are tried again for several hours, and the last fortnight’s are listed under the webhook, with what your server answered.
Ready recipes and apps
Settings → Integrations has ready recipes for the services a business already uses, with nothing else to sign up for and no code. Press Turn on, and Sema gives an address to paste into the other service:
- Typeform, HubSpot, Shopify, a Google Sheet, or anything that posts JSON: a new response, contact, order or row welcomes the person through one of your lead forms, with its template, its follow-up and its protections (their yes, an hourly limit, one welcome a month, never to someone who said STOP).
- Calendly: a booking schedules a reminder template before the meeting, and a cancellation takes it back.
Where the service signs what it sends (Typeform, Calendly and Shopify), Sema checks the signature and refuses a post that does not match. Each recipe lists what came of the last things it received, and why anything was not sent. The steps for each service are under the recipe, in that service's own words.
For more than that, Sema has its own apps for Zapier and n8n, and plugins for WooCommerce, ERPNext and Moodle, each connected with a live API key.
ChatGPT, Claude and other assistants
ChatGPT, Claude, Gemini and other AI assistants that can use connectors (MCP) can work with your workspace: tell you today's numbers, find a customer, read a conversation, send a message or a template, and start a campaign you have built. Ask it in your own words: “how many messages did we send today?”, “send Wanjiku the order_ready template for order 1042”.
- In the assistant, add a connector (in ChatGPT and Claude, under their settings for connectors) with the address
https://sema.datacare.co.ke/api/mcp. - It sends you to Sema. Sign in, choose the workspace, and tick what it may do: read conversations, find contacts, see templates, send, start campaigns.
- Press Allow. The assistant gets a key for exactly that, named after it, which you see and can revoke in Settings → API keys.
Only owners and admins can connect one. It can do only what you ticked, it is told to ask you before it sends anything or starts a campaign, and every message it sends is checked, charged and marked like any other sent through the API. Tools that take an address and a key instead (Claude Code, Cursor) use a key you make in Settings → API keys; the full reference says how.
The full reference
The API reference has every endpoint, with examples: sending text and templates, sending pictures, videos and documents such as a PDF invoice, sending later, what happened to a message, contacts, one-time codes, errors, and checking a webhook’s signature.
The same is described in OpenAPI at /api/v1/openapi.json, for Postman, Insomnia or a generated client.
Not what you needed? Ask us.