Integrations: connect your system to TalkAI
Who it's for: account admins and the developers of the system being connected
What it's for
With integrations, your system (orders, appointments, bookings or deliveries) asks TalkAI to reach your customers on WhatsApp and gets the result back, without anyone on your team writing to them one by one.
For example: your system asks to "confirm order P-1001 with this customer". TalkAI sends them the WhatsApp template, the AI agent talks with the customer, records that they confirmed, and your system receives a signed notification with the result.
Some uses:
- Confirm an appointment the day before and tell your calendar whether the customer is coming.
- Confirm a delivery: let the customer know the order is on its way and ask whether someone will be there to receive it.
- Confirm a booking and record any changes the customer asks for.
How it works, in a nutshell
- Your system launches a campaign through the API, with the contacts and each one's items.
- TalkAI sends each contact the WhatsApp template of the flow you chose.
- When the contact replies, the conversation goes to the flow's AI agent, which knows which items it has to resolve.
- The agent records the status and result of each item.
- Every change reaches your system through a webhook. You can also query it through the API at any time.
Concepts
API key and permissions
It is the credential your system uses to call the TalkAI API. It is created in Settings > Integrations, starts with tk_live_ and is shown only once: TalkAI only stores a fingerprint, so if you lose it, create a new one and revoke the old one.
Each key has its own permissions:
| Permission | In the panel | What it allows |
|---|---|---|
campaigns:write | Launch campaigns | Create campaigns |
items:read | Query items | Query campaigns and items |
items:write | Change item status | Resolve, cancel or reopen an item |
Revoking a key disables it immediately. The panel shows when it was last used.
Webhook and signature
The webhook is the URL of your system where TalkAI notifies every change. There is one per organization and it is registered in the panel: it never travels in API requests.
Every notification is signed with a secret that starts with whsec_ (HMAC-SHA256), so your system can check that TalkAI sent it and nobody changed it. Optionally, we also send a token of yours in the Authorization: Bearer header. When you rotate the secret, the previous one keeps signing for 24 h so you can switch without breaking anything. The details are in Webhooks.
Flow
A flow is the recipe for each kind of contact: which WhatsApp template is sent, which data fills its variables, which AI agent handles it, which item type it manages (for example pedido or turno), what result is expected and how many times sending is retried. Your system only knows its identifier, the slug (for example confirmar_pedidos).
Organization admins create and edit flows in the Flows section of the Integrations tab. If your plan does not include integrations yet, you see them in read-only mode.
Item and its statuses
An item is each thing to resolve with a contact: an order, an appointment, a booking. It is identified by its type (defined by the flow) and your own id, the external_id (for example P-1001). It carries two blocks of data:
data: what your system sends (product, date, address...). The template uses it and the agent sees it.result: what the agent records (for example{ "respuesta": "confirma" }). If the flow has a result schema, anything that does not match it is rejected before it reaches your system.
| Status | Meaning |
|---|---|
open | Pending: it was sent (or will be) and is waiting for a reply |
in_progress | The contact replied and the agent is handling it, or something is left to clarify |
resolved | Resolved |
cancelled | Cancelled: the contact can't make it or your system cancelled it |
expired | Expired without a reply (not used yet) |
Who changes each status:
- TalkAI moves the item to
in_progresswhen the contact replies. - The AI agent moves it to
in_progress,resolvedorcancelled, and records the result. - Your system, through the API, moves it to
resolvedorcancelled, or reopens it (open) with a reason.
API campaign
A campaign is an API request with the flow slug, your own campaign id (external_id) and the list of contacts, each with their phone and their items. If you send the same campaign twice, the second time nothing is sent again: it returns the existing one. If the same phone appears several times, its items are merged into a single contact. Sending follows the flow's time window, retries and expiration.
If the contact is already in a conversation
- If they have an open conversation with the AI agent of the same flow, the new request joins that conversation: the agent sees all the open items and, when in doubt, asks the contact which one they mean.
- If the conversation is handled by a person or another agent, or it is in the queue, sending waits and goes out when that conversation is closed. Meanwhile, the contact shows as deferred (
deferred) in the campaign.
Who can use them
- Integrations depend on the plan, or on the TalkAI team enabling them for your organization. The free trial does not include them.
- Organization admins manage API keys and the webhook.
- Organization admins also create and edit flows.
If the organization loses integrations, the API answers INTEGRATION_NOT_ENABLED, API campaigns stop sending new messages and notifications are paused until they are re-enabled. Nothing is deleted: keys, flows, items and pending notifications are kept, and ongoing conversations carry on normally.
expired status and the delivery log in the panel.Next: Set up an integration, API reference and Webhooks.