# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.wotnot.io/deploy/publishing-agents/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.