# Public APIs

## Authorization

All of WotNot's APIs use a Bearer token based authentication.

Your account token can be found at Settings > Account Settings > Developer.

<figure><img src="https://360969599-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsrMxU8nO3RjusUiYuXBB%2Fuploads%2Fx0r6Gyg5ZssWtnSULo9G%2FCleanShot%202025-11-10%20at%2011.51.25.png?alt=media&#x26;token=1306d8ec-20bb-479f-a5a5-435e3cb07508" alt=""><figcaption></figcaption></figure>

## Endpoint URL

Endpoint URL for all API integration with WotNot APIs are:

<kbd><https://api.wotnot.io></kbd>

## Create a knowledge base

<mark style="color:orange;">`POST`</mark> `/v1/ai/knowledge-base`

Using this API, you can create a knowledge base in the account.

**Headers**

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

**Body**

```json
{
  "name": "KNOWLEDGE_BASE_NAME"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true,
    "id": KNOWLEDGE_BASE_ID,
    "message": "Knowledge base has been created.",
    "code": "CREATE_KNOWLEDGE_BASE_SUCCESS_MESSAGE"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "ok": false,
    "message": "You have reached the maximum number of knowledge bases. Upgrade your plan to create more knowledge bases.",
    "error": "MAX_KNOWLEDGE_BASE_COUNT_EXCEEDED",
    "code": "MAX_KNOWLEDGE_BASE_COUNT_EXCEEDED"
}

{
    "ok": false,
    "message": "Please reach out to support to use this feature",
    "error": "UNAUTHORIZED_FEATURE",
    "code": "UNAUTHORIZED_FEATURE"
}
```

{% endtab %}
{% endtabs %}

## Adding text/file data sources to a knowledge base

<mark style="color:orange;">`POST`</mark> `/api/v1/ai/knowledge-base/<knowledge_base_id>/upload/sources`

Using this API, you can add a data source to an existing knowledge base.

**Headers**

| Name          | Value                 |
| ------------- | --------------------- |
| Content-Type  | `multipart/form-data` |
| Authorization | `Bearer <token>`      |

**Body**

The API accepts files and text as multipart form data for upload. Each form field should be a unique key and contain either a file or text content.

{% tabs %}
{% tab title="File" %}

| Name                     | Type      | Value         |
| ------------------------ | --------- | ------------- |
| file\_data\_source\_name | form-data | File location |
| {% endtab %}             |           |               |

{% tab title="Text" %}

| Name                     | Type      | Value        |
| ------------------------ | --------- | ------------ |
| text\_data\_source\_name | form-data | Text content |
| {% endtab %}             |           |              |
| {% endtabs %}            |           |              |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "q1": [
    {
      "id": 330783,
      "type": "text",
      "name": "sample.txt",
      "status": "in-progress",
      "errors": null
    },
    {
      "id": 330784,
      "type": "text",
      "name": "sample2.txt",
      "status": "in-progress",
      "errors": null
    },
    {
      "id": 330785,
      "type": "file",
      "name": "File.pdf",
      "status": "in-progress",
      "errors": null
    }
  ],
  "d2": [
    {
      "id": 330786,
      "type": "file",
      "name": "File2.pdf",
      "status": "in-progress",
      "errors": null
    }
  ],
  "knowledge_base_id": 876,
  "ok": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": "KNOWLEDGE_BASE_NOT_FOUND",
  "message": "KnowledgeBase Not Found in DB!",
  "code": "KNOWLEDGE_BASE_NOT_FOUND",
  "status": 404
}
{
  "ok": false,
  "error": "JWT_SIGNATURE_EXCEPTION",
  "message": "Invalid JWT token",
  "status": 401
}
{
  "ok": false,
  "error": "UNAUTHORIZED_FEATURE",
  "code": "UNAUTHORIZED_FEATURE",
  "status": 401,
  "message": "Please reach out to support to use this feature"
}
{
  "ok": false,
  "error": "ACCOUNT_DETAILS_NOT_FOUND",
  "code": "ACCOUNT_DETAILS_NOT_FOUND",
  "status": 404,
  "message": "Account Details are Not Found!"
}
{
  "ok": false,
  "error": "BAD_REQUEST",
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Knowledge base does not belong to the account(876)"
}
```

{% endtab %}
{% endtabs %}

## Adding individual URLs data sources to a knowledge base

<mark style="color:orange;">`POST`</mark> `/v1/ai/knowledge-base/<knowledge_base_id>/data-sources/webpages`

Using this API, you can add individual URLs as data sources to an existing knowledge base.

**Headers**

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

**Body**

```
{
    "urls": [
        "https://wotnot.io",
        "https://wotnot.io/pricing"
    ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true,
    "data_sources": [
        {
            "knowledge_base_id": "29",
            "id": 1335,
            "name": "https://wotnot.io",
            "source_type": "url",
            "token": 0,
            "refresh_frequency": null,
            "last_trained_at": null,
            "status": "in-progress",
            "type": "url",
            "created_at": "2025-07-07 05:09:34.218507",
            "created_by": {
                "id": 2,
                "name": "System"
            }
        },
        {
            "knowledge_base_id": "29",
            "id": 1336,
            "name": "https://wotnot.io/pricing",
            "source_type": "url",
            "token": 0,
            "refresh_frequency": null,
            "last_trained_at": null,
            "status": "in-progress",
            "type": "url",
            "created_at": "2025-07-07 05:09:34.218507",
            "created_by": {
                "id": 2,
                "name": "System"
            }
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "BAD_REQUEST",
    "ok": false,
    "status": 400,
    "message": [
        {
            "message": "\"urls[0]\" must be a valid uri",
            "path": [
                "urls",
                0
            ]
        },
        {
            "message": "\"urls\" does not contain 1 required value(s)",
            "path": [
                "urls"
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```
{
    "message": "Please reach out to support to use this feature",
    "ok": false,
    "error": "UNAUTHORIZED_FEATURE",
    "code": "UNAUTHORIZED_FEATURE",
    "status": 401
}
```

{% endtab %}
{% endtabs %}

## Adding domain data source to a knowledge base

<mark style="color:orange;">`POST`</mark> `/v1/ai/knowledge-base/<knowledge_base_id>/data-sources/domain`

Using this API, you can add domain as data source to an existing knowledge base.

**Headers**

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

**Body**

```
{
    "type": "domain",
    "url": "https://wotnot.io",
    "exclude_urls": "",
    "refresh_frequency": null
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true,
    "domain_id": 8,
    "request_id": "3QWuobWJE3jF065037422196qAdTZ2Ct"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "Maximum urls allowed 4",
    "ok": false,
    "error": "BAD_REQUEST",
    "code": "BAD_REQUEST",
    "status": 400
}

{
    "error": "BAD_REQUEST",
    "ok": false,
    "status": 400,
    "message": [
        {
            "message": "\"url\" must be a valid uri",
            "path": [
                "url"
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```
{
    "message": "Please reach out to support to use this feature",
    "ok": false,
    "error": "UNAUTHORIZED_FEATURE",
    "code": "UNAUTHORIZED_FEATURE",
    "status": 401
}
```

{% endtab %}
{% endtabs %}

## Deleting data sources from a knowledge base

<mark style="color:red;">`DELETE`</mark> `/v1/ai/knowledge-bases/<knowledge_base_id>/data-sources`

Using this API, you can delete data sources from an existing knowledge base.

**Headers**

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

**Body**

```json
{
    "data_sources": [
        <data_source_id_1>,
        <data_source_id_2>
    ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "ok": true
}
</code></pre>

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "BAD_REQUEST",
    "ok": false,
    "status": 400,
    "message": [
        {
            "message": "\"data_sources\" is required",
            "path": [
                "data_sources"
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "message": "Resource not found",
    "ok": false,
    "error": "RESOURCE_NOT_FOUND",
    "code": "RESOURCE_NOT_FOUND",
    "status": 404
}
```

{% endtab %}
{% endtabs %}

## Get training status of a data source <a href="#get-training-status-of-a-data-source" id="get-training-status-of-a-data-source"></a>

<mark style="color:green;">`GET`</mark> `/api/v1/ai/status/sources`

Using this API, you can fetch the status of one or more data sources in a knowledge base to know it its training is - in progress / completed / failed.

**Headers**

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

**Body**

| Name         | Type         | Description                                                               |
| ------------ | ------------ | ------------------------------------------------------------------------- |
| `source_ids` | query params | Comma-separated list of data source IDs to be passed as **query params**. |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "sources": [
        {
            "id": 330778,
            "name": "sample.txt",
            "status": "in-progress",
            "knowledge_base_id": 876
        }
    ],
    "ok": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": "JWT_SIGNATURE_EXCEPTION",
  "message": "Invalid JWT token",
  "status": 401
}
{
  "ok": false,
  "error": "UNAUTHORIZED_FEATURE",
  "code": "UNAUTHORIZED_FEATURE",
  "status": 401,
  "message": "Please reach out to support to use this feature"
}
{
  "ok": false,
  "error": "ACCOUNT_DETAILS_NOT_FOUND",
  "code": "ACCOUNT_DETAILS_NOT_FOUND",
  "status": 404,
  "message": "Account Details are Not Found!"
}
```

{% endtab %}
{% endtabs %}

## Fetch knowledge base details

<mark style="color:green;">`GET`</mark> `/v1/ai/knowledge-base/<knowledge_base_id>`

Using this API, you can fetch knowledge base and it's relevant data sources details.

**Headers**

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

**Body**

```json
{
  "limit": 100,
  "offset": 1
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true,
  "id": KNOWLEDGE_BASE_ID,
  "name": "KNOWLEDGE_BASE_NAME",
  "total_tokens": TOTAL_TOKENS_USED_IN_KNOWLEDGE_BASE,
  "total_data_sources": TOTAL_NUMBER_OF_DATA_SOURCES,
  "data_source": [
    {
      "id": DATA_SOURCE_ID,
      "name": "DATA_SOURCE_NAME",
      "source": "DATA_SOURCE_URL_OR_CONTENT",
      "token": TOTAL_TOKENS_USED_IN_DATA_SOURCE,
      "domain_id": DOMAIN_ID,
      "refresh_frequency": null,
      "last_trained_at": "2024-12-27 09:10:11.870000",
      "status": "trained",
      "failed_reason": null,
      "type": "url",
      "created_at": "2024-12-27 09:10:02.411000",
      "created_by": USER_ID,
      "user_name": "USER_NAME"
    }
  ],
  "domains": [],
  "pagination": {
    "limit": 100,
    "offset": 1,
    "total": TOTAL_NUMBER_OF_DATA_SOURCES
  },
  "last_trained_at": "2024-12-27 09:13:26.905000"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "ok": false,
    "message": "Resource not found",
    "error": "RESOURCE_NOT_FOUND",
    "code": "RESOURCE_NOT_FOUND"
}
```

{% endtab %}
{% endtabs %}

## Creating contacts

<mark style="color:orange;">`POST`</mark> `/v1/conversations`

Using this endpoint, you can create new contacts and update existing contacts.&#x20;

**Headers**

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

**Body**

Contains the contacts payload. Either "email" or "phone" is mandatory to create contact.

Pass all the custom contact variables in "custom\_variables" field.

```json
{
    "contacts": [
        {
            "name": "Michael Anderson",
            "email": "michael.anderson@example.com",
            "phone": "+1212555",
            "custom_variables": {
                "company": "Example Company"
            }
        },
        {
            "name": "Jessica Martinez",
            "email": "jessica.martinez@example.com",
            "phone": "+111221555",
            "custom_variables": {
                "company": "Example Company"
            }
        }
    ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "created": [
        {
            "id": 24135508,
            "external_key": "111221555_13361",
            "key": "6AFH8gyvwKCB073815082213IgPXtWMj",
            "ok": true
        }
    ],
    "updated": [
        {
            "id": 24135493,
            "external_key": "1212555_13361",
            "key": "7oFMaCsVoDD2073727174868hp2AavON",
            "ok": true
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "BAD_REQUEST",
    "ok": false,
    "status": 400,
    "message": [
        {
            "message": "\"contacts[0]\" must contain at least one of [email, phone]",
            "path": [
                "contacts",
                0
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}
{% endtabs %}

## Creating a conversation

<mark style="color:orange;">`POST`</mark> `/v1/conversations`

Using this endpoint, you can start/create a new conversation.&#x20;

**Headers**

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

**Body**

Contains the message payload. Payload differs based on channel.

{% tabs %}
{% tab title="WhatsApp" %}

```json
{
   "channel": "WHATSAPP",
   "from": "1123123123",
   "to": {
       "phone": "11231231230",
       "name": "John Doe",
       "email": "example@domain.com"
   },
   "message": {
       "type": "template",
       "data": {
           "template": "test_template",
           "parameters": {
               "header": [
                   "John"
               ],
               "body": [
                   "Doe",
                   "Doe2"
               ],
               "buttons": {
                   "copy_code": "123456",
                   "otp": "123456",
                   "url": "any"
               }
           },
           "variables":{
               "name": "John Doe"
           }
       }
   },
   "assignee": "agent_email@domain.com"
}
```

{% endtab %}

{% tab title="SMS" %}

```json
{
   "channel": "SMS",
   "from": "1-123-1231230",
   "to": {
       "phone": "1-1321231320",
       "name": "John Doe",
       "email": "abc@acme.com"
   },
   "message": {
       "type": "text",
       "text": "Hii"
   },
   "assignee": "agent_email@domain.com"
}
```

{% endtab %}
{% endtabs %}

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true,
  "conversation": {
    "id": "12wfegrgt4t",
    "message_id": "sdvgret4353b",
    "created_at": "",
    "assignee": {
      "id": 123,
      "to": "agent_email@domain.com"
    }
  },
  "contact": {
    "id": "11111111",
    "name": "John Doe",
    "phone": "1234567890",
    "email": "example@domain.com"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": "CHANNEL_TOKEN_EXPIRED",
  "code": "CHANNEL_TOKEN_EXPIRED",
  "message": "Token used to configure the channel is expired. Please reconfigure the channel.",
  "status": 400
}

{
  "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
}

{
  "ok": false,
  "error": "CONTACT_IS_BLOCKED",
  "code": "CONTACT_IS_BLOCKED",
  "message": "Conversation cannot be created for blocked contact.",
  "status": 400
}

{
  "ok": false,
  "error": "CONTACT_IS_BLOCKED",
  "code": "CONTACT_IS_BLOCKED",
  "message": "Conversation cannot be created for blocked contact.",
  "status": 400
}

{
  "ok": false,
  "error": "CONTACT_IS_BLOCKED",
  "code": "CONTACT_IS_BLOCKED",
  "message": "Conversation cannot be created for blocked contact.",
  "status": 400
}

{
  "ok": false,
  "error": "CONVERSATION_NOT_CREATED",
  "code": "CONVERSATION_NOT_CREATED",
  "message": "Conversation is not created due to user limit validation",
  "status": 400
}
```

{% endtab %}

{% tab title="401" %}

```json
{
   "error": "JWT_SIGNATURE_EXCEPTION",
   "message": "Invalid JWT token",
   "ok": false,
   "status": 401
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "ok": false,
  "error": "PHONE_NUMBER_IS_NOT_CONFIGURED",
  "code": "PHONE_NUMBER_IS_NOT_CONFIGURED",
  "message": "’From’ phone number is not configured in the account.",
  "status": 404
}

{
  "ok": false,
  "error": "WHATSAPP_TEMPLATE_NOT_FOUND",
  "code": "WHATSAPP_TEMPLATE_NOT_FOUND",
  "message": "WhatsApp template is not available in the account.",
  "status": 404
}

{
  "ok": false,
  "error": "TEMPLATE_NOT_APPROVED",
  "code": "TEMPLATE_NOT_APPROVED",
  "message": "Oops, template is not approved",
  "status": 404
}
```

{% endtab %}
{% endtabs %}

## Send agent response to a conversation

<mark style="color:orange;">`POST`</mark> `/api/v1/conversation/<conversation_id>/messages`

For every response sent by the agent on the third-party system, this API is to be invoked so it can relay this response to the user.

**Headers**

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

**Body**

{% tabs %}
{% tab title="Text" %}

```json
{
  "message": {
    "data": {
      "body": "Hi"
    },
    "type": "text"
  },
  "user": {
    "by": "agent_email@domain.com"
  }
}
```

{% endtab %}

{% tab title="File" %}

```json
{
  "message": {
    "file": {
      "path": "https://framerusercontent.com/images/L2xfXiiCkddPZOjvWCGTusENwb4.png",
      "size": 1,
      "type": "image/png",
      "name": "L2xfXiiCkddPZOjvWCGTusENwb4.png"
    },
    "type": "file"
  },
  "user": {
    "by": "agent_email@domain.com"
  }
}
```

{% endtab %}

{% tab title="Voice" %}

```json
{
  "message": {
    "file": {
      "path": "https://file-examples.com/storage/fe32d8b189680228b9ad370/2017/11/file_example_WAV_1MG.wav",
      "size": 1,
      "type": "audio/wav",
      "name": "file_example_WAV_1MG.wav"
    },
    "type": "voice"
  },
  "user": {
    "by": "agent_email@domain.com"
  }
}
```

{% endtab %}

{% tab title="Template message" %}

```json
{
  "message": {
    "data": {
      "template": "template_1"
    },
    "type": "template"
  },
  "user": {
    "by": "agent_email@domain.com"
  }
}
```

{% endtab %}
{% endtabs %}

**Response**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": "INVALID_DATA",
  "code": "INVALID_DATA",
  "message": "Error message",
  "status": 400
}

{
  "ok": false,
  "error": "CONVERSATION_CLOSED",
  "code": "CONVERSATION_CLOSED",
  "message": "Assignee cannot be changed on closed conversation.",
  "status": 400
}

{
  "ok": false,
  "error": "CONVERSATION_ASSIGNED_TO_BOT",
  "code": "CONVERSATION_ASSIGNED_TO_BOT",
  "message": "Agent message cannot be sent on bot assigned conversation.",
  "status": 400
}

{
  "ok": false,
  "error": "CONTACT_IS_BLOCKED",
  "code": "CONTACT_IS_BLOCKED",
  "message": "Conversation cannot be created for blocked contact.",
  "status": 400
}

{
  "ok": false,
  "error": "MESSAGE_NOT_SENT",
  "code": "MESSAGE_NOT_SENT",
  "message": "Message is not sent due to user limit validation.",
  "status": 400
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "ok": false,
  "error": "JWT_SIGNATURE_EXCEPTION",
  "code": "JWT_SIGNATURE_EXCEPTION",
  "message": "Invalid JWT token",
  "status": 401
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "ok": false,
  "error": "CONVERSATION_NOT_FOUND",
  "code": "CONVERSATION_NOT_FOUND",
  "message": "Conversation is not available.",
  "status": 404
}
```

{% endtab %}
{% endtabs %}

## Closing a conversation

<mark style="color:orange;">`POST`</mark> `/api/v1/conversation/<conversation_id>/events`

Use this endpoint to close an open conversation.

**Headers**

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

**Body**

```json
{
  "event": "status",
  "status": "CLOSE",
  "user": {
    "by": "agent_email@domain.com"
  }
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": "CONVERSATION_NOT_CLOSED",
  "code": "CONVERSATION_NOT_CLOSED",
  "message": "Conversation is not closed due to user limit validation.",
  "status": 400
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "ok": false,
  "error": "JWT_SIGNATURE_EXCEPTION",
  "code": "JWT_SIGNATURE_EXCEPTION",
  "message": "Invalid JWT token",
  "status": 401
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "ok": false,
  "error": "CONVERSATION_NOT_FOUND",
  "code": "CONVERSATION_NOT_FOUND",
  "message": "Conversation is not available.",
  "status": 404
}
```

{% endtab %}
{% endtabs %}

## Changing assignee in a conversation

<mark style="color:orange;">`POST`</mark> `/api/v1/conversation/<conversation_id>/events`

Use this endpoint to change the assignee in an open conversation.

**Headers**

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

**Body**

```json
// Change from assignee to assignee
{
  "event": "assignee",
  "user": {
    "by": "agent_email@domain.com",
    "to": "assignee@domain.com"
  }
}

// Change from assignee to team
{
  "event": "assignee",
  "team": {
    "by": "agent_email@domain.com",
    "to": "Sales"
  }
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": "TEAM_NOT_FOUND",
  "code": "TEAM_NOT_FOUND",
  "message": "Team does not exist.",
  "status": 400
}


{
  "ok": false,
  "error": "CONVERSATION_CLOSED",
  "code": "CONVERSATION_CLOSED",
  "message": "Assignee cannot be changed on closed conversation.",
  "status": 400
}


{
  "ok": false,
  "error": "ASSIGNEE_CHANGE_EXCEPTION",
  "code": "ASSIGNEE_CHANGE_EXCEPTION",
  "message": "By and To user are same. Can not assign conversation to same user.",
  "status": 400
}


{
  "ok": false,
  "error": "ASSIGNEE_NOT_CHANGED",
  "code": "ASSIGNEE_NOT_CHANGED",
  "message": "Assignee is not changed due to user limit validationt.",
  "status": 400
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "ok": false,
  "error": "JWT_SIGNATURE_EXCEPTION",
  "code": "JWT_SIGNATURE_EXCEPTION",
  "message": "Invalid JWT token",
  "status": 401
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "ok": false,
  "error": "CONVERSATION_NOT_FOUND",
  "code": "CONVERSATION_NOT_FOUND",
  "message": "Conversation is not available.",
  "status": 404
}
```

{% endtab %}
{% endtabs %}

## Update variable of a conversation

<mark style="color:orange;">`POST`</mark> `/v1/accounts/<account_id>/conversations/<conversation_id>/variables`

Use this endpoint to update the variables in the conversation.

**Headers**

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

**Body**

```json
{
  "variables": [
    {
      "name": "name",
      "type": "conversation",
      "value": "John Doe"
    },
    {
      "name": "phone",
      "type": "contact",
      "value": "9999999999"
    },
    {
      "name": "company",
      "type": "conversation",
      "value": "Example"
    },
    {
      "name": "email",
      "type": "contact",
      "value": "john.doe@gmail.com"
    }
  ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "ok": false,
    "message": {
        "variables": [
            "Shorter than minimum length 1."
        ]
    },
    "status": 400,
    "error": "BAD_REQUEST"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "message": "Conversation is not found",
    "ok": false,
    "error": "CONVERSATION_NOT_FOUND",
    "code": "CONVERSATION_NOT_FOUND",
    "status": 404
}
```

{% endtab %}
{% endtabs %}

## Set webhook URL for Events feature

<mark style="color:orange;">`POST`</mark> `/v1/accounts/<account_id>/webhook`

Use this endpoint to set webhook for receiving conversation related events from the account.

**Headers**

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

**Body**

```json
{
  "webhook_url": "",
  "subscribed_events": [
    {
      "key": "conversation_create",
      "is_subscribed": true
    },
    {
      "key": "message",
      "is_subscribed": true
    },
    {
      "key": "status",
      "is_subscribed": true
    },
    {
      "key": "assignee_change",
      "is_subscribed": true
    },
    {
      "key": "sla_breached",
      "is_subscribed": true
    },
    {
      "key": "variables",
      "is_subscribed": true
    },
    {
      "key": "conversation_labels",
      "is_subscribed": true
    },
    {
      "key": "note",
      "is_subscribed": true
    }
  ],
  "is_enabled": true,
  "token": "Test"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}
{% endtabs %}

## Create a bot

<mark style="color:orange;">`POST`</mark> `/v1/bot`

Using this API, you can create a bot in account.

**Headers**

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

**Body**

```json
{
  "name": "BOT_NAME",
  "template_id": REFERENCE_BOT_ID,
  "channel": "API"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true,
    "id": BOT_ID
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "ok": false,
    "message": "Maximum bots limit reached for the account.",
    "error": "MAXIMUM_BOTS_LIMIT_REACHED",
    "code": "MAXIMUM_BOTS_LIMIT_REACHED"
}
```

{% endtab %}
{% endtabs %}

## Fetch bot flow

<mark style="color:green;">`GET`</mark> `/v1/bots/<bot_id>/flow`

Using this API, you can fetch bot's flow data.

**Headers**

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

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true,
    "data": "BOT_FLOW_JSON",
    "is_deployed": true,
    "last_deployed_at": "2025-05-05 10:37:43.128000"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "error": "BOT_NOT_FOUND",
    "ok": false,
    "status": 404,
    "message": "Bot not found."
}
```

{% endtab %}
{% endtabs %}

## Deploy bot flow

<mark style="color:orange;">`POST`</mark> `/v1/bots/<bot_id>/deploy`

Using this API, you can deploy the bot flow after modifying it's JSON data.

**Headers**

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

**Body**

```json
{
  "flow_diagram": "BOT_FLOW_JSON"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true,
    "data": "BOT_FLOW_JSON",
    "is_deployed": true,
    "last_deployed_at": "2025-05-05 10:37:43.128000"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "error": "BOT_NOT_FOUND",
    "ok": false,
    "status": 404,
    "message": "Bot not found."
}
```

{% endtab %}
{% endtabs %}

## Fetch bots list

<mark style="color:green;">`GET`</mark> `/v1/accounts/<account_id>/bots`

Use this endpoint to fetch list of bots available in the account.

**Headers**

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

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true,
  "bots": [
    {
      "bot_title": "Appointment Booking",
      "channels": [
        {
          "name": "WEB"
        }
      ],
      "is_active": false,
      "bot_key": "7SgQLb4qUbp61059137828254t5QVE0H",
      "last_deployed_at": "2025-01-22 13:26:40.554000",
      "is_inactive_by_system": false,
      "priority": 1,
      "preferred_bot_language": {
        "label": "English",
        "code": "EN"
      },
      "type": "inbound",
      "outbound_type": null,
      "bot_owner": {
        "id": 14764,
        "name": "John Doe"
        "email": "john.doe@gmail.com"
      }
      "created_at": "2024-02-09 10:59:13.783000",
      "preview_key": "6H7PD4WwTmsU105913782825Zk3KCj3t",
      "bot_id": 9633
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}
{% endtabs %}

## Fetch account roles

<mark style="color:green;">`GET`</mark> `/v1/accounts/<account_id>/user-roles`

Use this endpoint to fetch all the user roles available in the account.

**Headers**

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

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "roles": [
    {
      "role_configuration": {
        "live_chat": {
          "settings": true,
          "full_access": true,
          "human_handover": true
        },
        "analytics": {
          "full_access": true
        },
        "support_ticket": {
          "full_access": true
        },
        "bot_builder": {
          "full_access": true,
          "read_only_access": true
        },
        "ticket": {
          "full_access": true
        },
        "account_settings": {
          "teammates": true,
          "billing": true,
          "variables": true,
          "automation": true,
          "csat": true,
          "teams": true,
          "events": true,
          "settings": true,
          "link_tracking": true
        },
        "ai_studio": {
          "full_access": true
        },
        "contacts": {
          "full_access": true
        },
        "app_market": {
          "full_access": true
        },
        "channel_configuration": {
          "sms": {
            "opt_out_management": true,
            "configuration": true
          },
          "web": {
            "appearance": true,
            "trigger_conditions": true,
            "pop_up_messages": true,
            "configuration": true,
            "general_settings": true
          },
          "whatsapp": {
            "templates": true,
            "configuration": true
          },
          "instagram": {
            "configuration": true
          },
          "facebook": {
            "configuration": true
          },
          "voice": {
            "configuration": true
          },
          "email": {
            "templates": true,
            "configuration": true
          }
        }
      },
      "users_in_role": [
        {
          "user_type_id": 1,
          "image_url": null,
          "last_name": "Doe",
          "first_name": "John",
          "id": 112233,
          "email": "john.doe@gmail.com"
        }
      ],
      "master_role_id": 2,
      "id": 99,
      "role_name": "admin",
      "description": "Has complete access to configure and manage every aspect of the platform.",
      "created_at": "04-Jan-26, 01:13 AM"
    }
  ],
  "ok": true,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total": 1
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}
{% endtabs %}

## Invite user to account

<mark style="color:orange;">`POST`</mark> `/v1/accounts/<account_id>/user`

Using this API, you can invite user to the account.

**Headers**

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

**Body**

```json
{
    "user": {
        "email": "john.doe@gmail.com",
        "first_name": "John", // Optional
        "last_name": "Doe", // Optional
        "role_id": "262185" // Role ID received from "Fetch account roles" API
    },
    "notify_user": "true"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "invitation_link": "{{customer_portal_domain}}/create-your-account?invitation_key={{invitation_key}}",
    "ok": true,
    "status": "invited"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "BAD_REQUEST",
    "ok": false,
    "status": 400,
    "message": [
        {
            "message": "\"user.email\" must be a valid email",
            "path": [
                "user",
                "email"
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
 {
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}

{% tab title="404" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "error": "ROLE_NOT_FOUND",
    "ok": false,
    "status": 404,
    "message": "Role not found for this account."
}
</code></pre>

{% endtab %}
{% endtabs %}

## Update user role

<mark style="color:blue;">`PUT`</mark> `/v1/accounts/<account_id>/users/<user_id>`

Using this API, you can update the role of user.

**Headers**

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

**Body**

```json
{
    "role_id": "262185" // Role ID received from "Fetch account roles" API
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "BAD_REQUEST",
    "ok": false,
    "status": 400,
    "message": [
        {
            "message": "\"role_id\" must be a number",
            "path": [
                "role_id"
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
 {
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "error": "USER_NOT_FOUND",
    "ok": false,
    "status": 404,
    "message": "User not found in this account."
}

{
    "error": "ROLE_NOT_FOUND",
    "ok": false,
    "status": 404,
    "message": "Role not found for this account."
}
```

{% endtab %}
{% endtabs %}

## Remove user from account

<mark style="color:red;">`DELETE`</mark> `/v1/accounts/<account_id>/users/<user_id>`

Using this API, you can remove user from the account.

**Headers**

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

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "ok": true
}
```

{% endtab %}

{% tab title="401" %}

```json
 {
    "error": "UNAUTHORIZED",
    "ok": false,
    "status": 401,
    "message": "Invalid token. Provide the valid account token."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "error": "USER_NOT_FOUND",
    "ok": false,
    "status": 404,
    "message": "User not found in this account."
}
```

{% endtab %}
{% endtabs %}