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:

How it works, in a nutshell

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:

PermissionIn the panelWhat it allows
campaigns:writeLaunch campaignsCreate campaigns
items:readQuery itemsQuery campaigns and items
items:writeChange item statusResolve, 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:

StatusMeaning
openPending: it was sent (or will be) and is waiting for a reply
in_progressThe contact replied and the agent is handling it, or something is left to clarify
resolvedResolved
cancelledCancelled: the contact can't make it or your system cancelled it
expiredExpired without a reply (not used yet)

Who changes each status:

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

Who can use them

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.

ℹ️
Note:Not available yet: the automatic message to the contact when you reopen an item, automatic reminders, the expired status and the delivery log in the panel.

Next: Set up an integration, API reference and Webhooks.