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.

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

Build your chatbot flow

Go to Bot builder > Choose “API” as channel
Build your conversation flow
Hit “Deploy” to publish your version

Configure WotNot's APIs

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

Start conversation - To initiate the conversation and create a thread.
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

Open your WotNot account.
Go to Settings > Account Settings > Developer.
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>

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

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

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

{
  "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,
    "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/<conversation_id>/messages

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

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

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

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

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

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

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

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

{
  "error": "Invalid request"
}

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

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

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.

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.

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.

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.

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.

The API behaves differently from the Web widget

Getting started

Build

Operate

Deploy

Reports

Account

API

When to use the API

Build your API channel

Authentication

Getting credentials

Authenticating a request

Start conversation

Endpoint

Headers

Body

Response

Passing initial context

Continuing a conversation

Endpoint

Header

Session Lifetime

Handling interactive elements

Handover to a human

Rate limits and errors

Troubleshooting

​When to use the API

​Build your API channel

​Authentication

​Getting credentials

​Authenticating a request

​Start conversation

​Endpoint

​Headers

​Body

​Response

​Passing initial context

​Continuing a conversation

​Endpoint

​Header

​Session Lifetime

​Handling interactive elements

​Handover to a human

​Rate limits and errors

​Troubleshooting

When to use the API

Build your API channel

Authentication

Getting credentials

Authenticating a request

Start conversation

Endpoint

Headers

Body

Response

Passing initial context

Continuing a conversation

Endpoint

Header

Session Lifetime

Handling interactive elements

Handover to a human

Rate limits and errors

Troubleshooting