> For the complete documentation index, see [llms.txt](https://help.talkie.se/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.talkie.se/getting-started/publishing-your-bot/api.md).

# 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

{% hint style="info" %}
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.
{% endhint %}

#### 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**

```json
{
  "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": "example@domain.com",
      "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**

```json
{
  "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": "example@domain.com",
    "phone": "9999999999",
    "visitor_key": "<visitor_id>_<account_id>"
  }
}
```

{% hint style="warning" %}
Save `conversation.id` from the response – you need it for every following message in the conversation.
{% endhint %}

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)**

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

**Response – 200 OK**

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

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

{% hint style="success" %}
With these two calls in place, your system can run a full conversation with the chatbot built in ZyndraAI, using whatever interface you like.
{% endhint %}