Set up an integration
Who it's for: account admins
What it's for
This is the whole path, from asking for the feature to your system launching its first campaign. Everything admins do is in Settings > Integrations. If you have not read the concepts yet, start with Integrations: API and webhooks.
Step by step
➡️
Step:Ask for it to be enabled. Integrations come with the plan or with an enablement by the TalkAI team; the free trial does not include them. Until they are enabled, the tab shows Integrations not included in your plan: you can see what is configured, but you cannot create keys or change the webhook.
➡️
Step:Create an API key. In API keys click New key, give it a name that identifies the system that will use it and tick only the permissions it needs. Copy it right away: it is not shown again.
➡️
Step:Register the webhook. In Webhook enter the public URL (with
https) where your system receives notifications, optionally a Bearer token, choose the events, turn on Webhook active and click Save.➡️
Step:Store the signing secret. When you first save the webhook the secret is generated and shown only once: store it in your system to verify the signature.
➡️
Step:Test the webhook. Click Test webhook: TalkAI sends a signed
integration.ping event. Check that your system receives it, verifies the signature and answers with a 2xx code.➡️
Step:Build the flow. In Flows tap New flow and fill in the approved WhatsApp template, where each variable comes from, the AI agent with the Report integration items tool turned on, the item type, the result schema and the sending policy. Once saved it shows up in the list with its slug, which is what your system uses.
➡️
Step:Your system launches campaigns and receives notifications. With the key and the slug, your system creates campaigns with
POST /v1/campaigns and receives every change on the webhook. The details for developers are in API reference and Webhooks.What you need to define for the flow
To build the flow we will ask you for:
- What has to be resolved with the contact (confirm an appointment, a delivery, a booking) and which answers you expect.
- The template text and which item data fills its variables. The template must be approved by Meta and should be in the Utility category: Meta can reject or throttle templates that look like marketing.
- Which data your system sends in
datafor each item (for example product, date and address). - Which result you want to receive in
result(for examplerespuestaand anueva_fecha). With that we build the schema that validates what the agent records. - The sending policy: retries if the contact does not reply, how often, after how many hours it expires and during which hours it may be sent.
ℹ️
Note:The flow also stores a re-request template and a reminder policy, but automatic reminders and the message to the contact when you reopen an item are not available yet.
Good practices
- One key per system, with just the permissions it needs. If a system only reads, give it only Query items.
- Keep the secret and the key out of your code, in your system's secure configuration.
- Rotate the secret if you think it leaked: for 24 h the previous one keeps signing, so you can update your system without losing notifications.
- Do not rely on the webhook alone. If your system was down or the webhook was off, call
GET /v1/items?updated_since=to catch up.
⚠️
Warning:Revoking a key immediately cuts off any system that uses it. Before revoking it, load the new one into your system.