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

POST https://app.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": "[e-mail]",
      "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

200

{
    "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": "[e-mail]",
        "phone": "9999999999",
        "visitor_key": "<visitor_id>_<account_id>"
    }
}

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
}

401

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

Send visitor response

POST https://app.wotnot.io/api/v1/conversation/<conversation_id>/messages

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.

Headers

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

Body

Text

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

Button

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

Multi-button

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

Slider

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

File upload

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

Javascript

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

Response

200

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

400

{
  "error": "Invalid request"
}

401