> ## Documentation Index
> Fetch the complete documentation index at: https://help.wotnot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Deploy AI agents programmatically through an API and use your own chat interface, application, or system as the customer-facing experience.

![Image](https://mintcdn.com/wotnot/ZvBlY58cOcRHCVBj/images/image-615.png?fit=max\&auto=format\&n=ZvBlY58cOcRHCVBj\&q=85\&s=dcd395806ab023636fdd0283a0118d00)

We're adding API as a channel, so users can use the chatbot logic built on WotNot but utilize their own custom-made chat widget / launcher.

The API gives you the conversation engine while your application controls how messages, buttons, files, and other interactive elements are displayed.

> [!NOTE]
>
> You provide the interface and conversation handling on your side; WotNot provides the chatbot logic and processes visitor responses.

## When to use the API

Use the API channel when you want to keep WotNot's conversation logic but build your own customer-facing experience.

With the API, your application is responsible for rendering the conversation. This includes handling interactive responses such as buttons, multi-button options, sliders, file uploads, and other block types returned by the agent.

* You have a better chat widget UI
* You want to manage chatbots on multiple domains

| Option | When to use it | Development effort | What you control |
| - | - | - | - |
| **Web widget** | Add a chatbot to your website quickly | Low — little to no development required | Basic appearance and configuration |
| **Webview** | Show the existing WotNot chatbot inside your website or application | Medium — requires some development to embed it | Where and how the chatbot appears |
| **API** | Build your own chatbot interface or connect WotNot to a custom application | High — requires developer work | Full control over the chatbot interface and user experience |

# Build your API channel

**1. Build your chatbot flow**

1. Go to Bot builder > Choose "**API**" as channel
2. Build your conversation flow
3. Hit "**Deploy**" to publish your version

**2. Configure WotNot's APIs**

You would need to invoke 2 APIs to facilitate the chat between the chatbot built on WotNot and your system.

1. **Start conversation** - To initiate the conversation and create a thread.
2. **Send visitor message** - To send the visitor's reply to a message for WotNot to process and go to the next step in the chat flow.

With this your system will be able to smoothly interact with the chatbot built on WotNot.

# Authentication

WotNot APIs use Bearer token authentication.

### Getting credentials

1. Open your WotNot account.
2. Go to **Settings > Account Settings > Developer**.
3. Copy the API token provided for your account.

The token is an account-level credential and is used to authenticate requests to the WotNot API.

### Authenticating a request

Add the token to the **Authorization** header using the Bearer scheme.

| **Name** | **Value** |
| :- | :- |
| Content-Type | application/json |
| Authorization | Bearer \<token> |

> [!WARNING]
>
> Treat your API token as a server-side credential. Never expose it in browser-side JavaScript, mobile application code, or any other client-side environment where users can inspect it.

# Start conversation

### Endpoint

POST[https://api.wotnot.io/api/v1/conversations](https://api.wotnot.io/api/v1/conversations)

Initiates a chat session with a visitor. Make sure you use this API for unique visitors.

### Headers

| **Name** | **Value** |
| - | - |
| Content-Type | application/json |
| Authorization | Bearer \<token> |

### Body

```json theme={null}
{
  "channel": "API",
  "message": {
    "data": {
      "body": "Hello" // user message
    },
    "type": "text"
  },
  "variables": { // variables are optional to send
    "system": { 
      "timezone": "Asia/Calcutta",
      "referrerUrl": "https://wotnot.io",
      "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
  "from": {
    "user_external_id": "<visitor_id>", // mandatory to define a unique visitor id
    "type": "VISITOR"
  }
}
```

### Response

> [tab] 200
>
> ```json theme={null}
> {
>     "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>"
>     }
> }
> ```

> [tab] 400
>
> ```json theme={null}
> {
>   "ok": false,
>   "error": "CONVERSATION_CREATION_EXCEPTION",
>   "code": "CONVERSATION_CREATION_EXCEPTION",
>   "message": "Conversation is not created. Please try again after some time.",
>   "status": 400
> }
>
> {
>   "ok": false,
>   "error": "CHANNEL_NOT_ENABLED",
>   "code": "CHANNEL_NOT_ENABLED",
>   "message": "This channel is not enabled in the account.",
>   "status": 400
> }
> ```

> [tab] 401
>
> ```json theme={null}
> {
>     "ok": false,
>     "status": 401,
>     "error": "JWT_SIGNATURE_EXCEPTION",
>     "message": "Invalid JWT token"
> }
> ```

### Passing initial context

If your application already knows information about the visitor, pass that information when creating the conversation instead of asking the visitor for it again.

For example, your application may already know the visitor's:

* Name
* Email address
* Phone number
* Other supported visitor attributes

This lets the conversation start with the context your application already has.

# Continuing a conversation

Send all visitor responses received at your systems to WotNot using this API.

After receiving it, WotNot will process the visitor message as per the chatbot flow and provide the chatbot response.

### Endpoint

POST[https://api.wotnot.io/api/v1/conversation/\&lt;conversation\_id\&gt;/messages](https://api.wotnot.io/api/v1/conversation/\&lt;conversation_id\&gt;/messages)

### Header

| **Name** | **Value** |
| :- | :- |
| Content-Type | application/json |
| Authorization | Bearer \<token> |

### Session Lifetime

The conversation identifier returned by WotNot is used to associate subsequent visitor responses with the existing conversation.

Store this identifier in your application's session or conversation state and reuse it for subsequent messages.

# Handling interactive elements

> [tab] Text
>
> ```json theme={null}
> {
>   "message": {
>     "data": {
>       "body": "Hello" // visitor's message
>     },
>     "type": "text" 
>   },
>   "user": {
>     "type": "VISITOR"
>   }
> }
> ```

> [tab] Button
>
> ```json theme={null}
> {
>   "message": {
>     "data": {
>       "body": "Button 1",
>       "callback": "",
>       "next_dialog": "5",
>       "key": "4"
>     },
>     "type": "button.response"
>   },
>   "user": {
>     "type": "VISITOR"
>   }
> }
> ```

> [tab] Multi Button
>
> ```json theme={null}
> {
>   "message": {
>     "data": {
>       "body": "Button 1",
>       "callback": "",
>       "next_dialog": "4",
>       "key": "3",
>       "selected_button_index": [
>         "Button 1__0"
>       ]
>     },
>     "type": "button.response"
>   },
>   "user": {
>     "type": "VISITOR"
>   }
> }
> ```

> [tab] Slider
>
> ```json theme={null}
> {
>   "message": {
>     "type": "slider.response",
>     "data": {
>       "body": "30",
>       "value": 30,
>       "callback": null
>     }
>   },
>   "user": {
>     "type": "VISITOR"
>   }
> }
> ```

> [tab] File Upload
>
> ```json theme={null}
> {
>   "message": {
>     "type": "file_upload.response",
>     "data": {
>       "files": [
>         {
>           "filename": "7df2d331_foo.png",
>           "link": "https://wotnot.io/images/7df2d331_foo.png",
>           "mime_type": "image/png",
>           "extension": "png"
>         },
>         {
>           "filename": "7df2d338_bar.png",
>           "link": "https://wotnot.io/images/7df2d331_bar.png",
>           "mime_type": "image/png",
>           "extension": "png"
>         }
>       ]
>     }
>   },
>   "user": {
>     "type": "VISITOR"
>   }
> }
> ```

> [tab] JavaScript
>
> ```json theme={null}
> {
>   "message": {
>     "type": "javascript.response",
>     "data": {
>       "variables": {
>         "contact_variables": [
>           {
>             "name": "name",
>             "value": "John"
>           }
>         ],
>         "non_contact_variables": [
>           {
>             "name": "ans",
>             "value": "2"
>           }
>         ]
>       }
>     }
>   },
>   "user": {
>     "type": "VISITOR"
>   }
> }
> ```

### Handover to a human

If your conversation flow transfers the visitor to a human, your application should update the UI to indicate that the automated conversation has ended or that a human agent is taking over.

The exact handover response and human-agent workflow should be validated against the current API response schema before implementing a production client.

### Rate limits and errors

Every request should handle both successful and unsuccessful responses.

Common response statuses include:

| **Status** | **Meaning** | **Recommended behaviour** |
| :- | :- | :- |
| 200 | Request completed successfully | Process the response and update the conversation UI. |
| 400 | Invalid request or conversation state | Inspect the error response, correct the request, and do not blindly retry. |
| 401 | Authentication failed | Check the Bearer token and make sure the request is authenticated correctly. |

**Response:**

> [tab] 200
>
> ```json theme={null}
> {
>   "ok": true,
>   "message_id": "6HRBshHEcV8P103039226478taGDJQxC"
> }
> ```

> [tab] 400
>
> ```json theme={null}
> {
>   "error": "Invalid request"
> }
> ```

> [tab] 401
>
> ```json theme={null}
> {
>     "ok": false,
>     "status": 401,
>     "error": "JWT_SIGNATURE_EXCEPTION",
>     "message": "Invalid JWT token"
> }
> ```

Recommended behaviour:

* Do not retry a request automatically unless you know the operation is safe to retry.
* Use exponential backoff for retriable infrastructure failures.
* Avoid sending the same visitor message multiple times because of a client-side timeout.
* Log the conversation identifier and request outcome for troubleshooting.

> [!WARNING]
>
> Do not automatically retry every `400` or `404` response. First inspect the error and determine whether the request can succeed without changing the input or conversation state.

# Troubleshooting

> [accordion] Authentication is failing
>
> Check the following:
>
> * Confirm that the token is copied correctly.
> * Confirm that the request uses the `Authorization: Bearer <token>` format.
> * Make sure the token has not been exposed or altered.
> * Confirm that the request is being sent from your server-side application.
> * Check that the `Content-Type` header is set to `application/json` where required.

> [accordion] The conversation identifier is rejected on the second turn
>
> Check the following:
>
> * Confirm that you stored the `conversation.id` returned by the **Start conversation** request.
> * Make sure the same conversation identifier is used in the message endpoint.
> * Check that the identifier has not been truncated or modified.
> * Confirm that the conversation still exists and is available.

> [accordion] The response contains a block type my client does not handle
>
> Your client must support every response type used by the deployed flow.
>
> Check the flow for interactive blocks such as:
>
> * Buttons
> * Multi-button options
> * Sliders
> * File uploads
> * JavaScript responses
>
> Add a renderer for the response type or modify the flow to use a response type that your application supports.

> [accordion] The conversation stops unexpectedly
>
> Check the conversation state and the response returned by WotNot.
>
> Also verify that your application:
>
> * Preserves the correct `conversation_id` between turns.
> * Does not create a new conversation for every visitor message.

> [accordion] The API is being called repeatedly under load
>
> Check your application's retry logic and request concurrency.
>
> Make sure a timeout does not cause the same visitor message to be submitted multiple times.
>
> Add request logging so you can identify duplicate requests and the associated conversation identifiers.

> [accordion] The API behaves differently from the Web widget
>
> The Web widget provides its own rendering and interaction handling. The API does not provide the same customer-facing UI.
>
> Compare the following:
>
> * The deployed flow and channel configuration.
> * The exact request payload sent by your application.
> * The response type returned by WotNot.
> * How your application renders buttons, options, files, and other interactive content.
>
> If the same flow behaves differently, verify that your application is correctly implementing the response types returned by the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.