> For the complete documentation index, see [llms.txt](https://help.wotnot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.wotnot.io/deploy/publishing-agents/api.md).

# API

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.

#### Why is this helpful?

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

Following are the steps to use API as a channel:

## Step 1: Build your chatbot flow

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

## Step 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 goto the next step in the chat flow.

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

## Start conversation

<mark style="color:green;">`POST`</mark> `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
{
  "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**

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

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

{% endtab %}

{% tab title="400" %}

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

{% endtab %}

{% tab title="401" %}

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

{% endtab %}
{% endtabs %}

## Send visitor response

<mark style="color:green;">`POST`</mark> `https://api.wotnot.io/api/v1/conversation/<conversation_id>/messages`

Send all visitor responses received at your systems to WotNot using this API.&#x20;

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

**Headers**

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

**Body**

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

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

{% endtab %}

{% tab title="Button" %}

```json
{
  "message": {
    "data": {
      "body": "Button 1",
      "callback": "",
      "next_dialog": "5",
      "key": "4"
    },
    "type": "button.response"
  },
  "user": {
    "type": "VISITOR"
  }
}
```

{% endtab %}

{% tab title="Multi-button" %}

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

{% endtab %}

{% tab title="Slider" %}

```json
{
  "message": {
    "type": "slider.response",
    "data": {
      "body": "30",
      "value": 30,
      "callback": null
    }
  },
  "user": {
    "type": "VISITOR"
  }
}
```

{% endtab %}

{% tab title="File upload" %}

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

{% endtab %}

{% tab title="Javascript" %}

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

{% endtab %}
{% endtabs %}

**Response**

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

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

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}

{% tab title="401" %}

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

{% endtab %}
{% endtabs %}