API

Use the chatbot logic you build in ZyndraAI with your own custom chat widget or system.

The API channel lets you run the chatbot logic you build in ZyndraAI from your own system. Instead of ZyndraAI's chat widget, you use your own custom chat widget or launcher, and exchange messages with ZyndraAI through two API calls.

When is this useful?

• You have your own chat widget with a better fit for your brand or UI.

• You want to run chatbots across multiple domains from one place.

• You want to embed the chatbot in a system that isn't a website, such as an app or an internal tool.

How it works

Your system owns the user interface. ZyndraAI owns the conversation logic. Every message a visitor writes is sent to ZyndraAI, which runs it through the chat flow and returns the bot's reply for your system to display.

Step 1: Build your chatbot flow

1. Go to Bot builder and choose API as the channel.

2. Build your conversation flow as usual.

3. Click Deploy to publish your version.

Step 2: Connect your system to ZyndraAI's API

Two API calls are needed to run a chat between your system and the chatbot:

Call	What it does
Start conversation	Initiates the conversation for a visitor and creates a conversation thread.
Send visitor message	Sends the visitor's reply to ZyndraAI, which processes it and moves to the next step in the chat flow.

Both calls are authenticated with a Bearer token and expect JSON.

Header	Value
Content-Type	application/json
Authorization	Bearer <token>

Start conversation

POST https://api.talkie.se/api/v1/conversations

Initiates a chat session with a visitor. Call this once per unique visitor – every call creates a new conversation.

Request body

{
  "channel": "API",
  "message": {
    "data": {
      "body": "Hello"                 // the visitor's first message
    },
    "type": "text"
  },
  "variables": {                      // optional
    "system": {
      "timezone": "Europe/Stockholm",
      "referrerUrl": "https://talkie.se",
      "browserLanguage": "en-GB"
    },
    "contact": {
      "name": "User Name",
      "email": "[e-mail]",
      "phone": "1234567890"
    },
    "conversation": {
      "variable": "value"
    }
  },
  "bot_key": "<bot_key>",             // found on the trigger block in Bot builder
  "from": {
    "user_external_id": "<visitor_id>", // required – a unique ID for the visitor
    "type": "VISITOR"
  }
}

Field	Required	Description
channel	Yes	Always API.
message	Yes	The visitor's first message.
bot_key	Yes	Identifies the bot. You find it on the trigger block in Bot builder.
from.user_external_id	Yes	A unique ID for the visitor in your system. Used to keep conversations apart.
variables	No	Pre-fill system, contact and conversation variables that the chat flow can use.

Response – 200 OK

{
  "ok": true,
  "conversation": {
    "id": "<conversation_id>",
    "created_at": "2025-02-10 20:21:03.913000",
    "assignee": {
      "id": "<bot_user_id>",
      "to": "<bot_user_email>"
    }
  },
  "contact": {
    "name": "User Name",
    "email": "[e-mail]",
    "phone": "9999999999",
    "visitor_key": "<visitor_id>_<account_id>"
  }
}

Save conversation.id from the response – you need it for every following message in the conversation.

Other status codes: 400 – the request body is invalid or a required field is missing. 401 – the token is missing or invalid.

Send visitor message

POST https://api.talkie.se/api/v1/conversation/<conversation_id>/messages

Send every visitor reply your system receives to ZyndraAI with this call. ZyndraAI processes the message according to the chat flow and returns the chatbot's response.

Request body (text message)

{
  "message": {
    "data": {
      "body": "Hello"                 // the visitor's message
    },
    "type": "text"
  },
  "user": {
    "type": "VISITOR"
  }
}

Response – 200 OK

{
  "ok": true,
  "message_id": "6HRBshHEcV8P103039226478taGDJQxC"
}

Other status codes: 400 – the request body is invalid. 401 – the token is missing or invalid.

With these two calls in place, your system can run a full conversation with the chatbot built in ZyndraAI, using whatever interface you like.