Public APIs
Authorization
All of WotNot's APIs use a Bearer token based authentication.
Your account token can be found at Settings > Account Settings.
Create a knowledge base
POST /v1/ai/knowledge-base
Using this API, you can create a knowledge base in the account.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"name": "KNOWLEDGE_BASE_NAME"
}Response
{
"ok": true,
"id": KNOWLEDGE_BASE_ID,
"message": "Knowledge base has been created.",
"code": "CREATE_KNOWLEDGE_BASE_SUCCESS_MESSAGE"
}{
"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"
}Adding text/file data sources to a knowledge base
POST /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
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.
file_data_source_name
form-data
File location
text_data_source_name
form-data
Text content
Response
{
"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
}{
"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)"
}Adding individual URLs data sources to a knowledge base
POST /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
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"urls": [
"https://wotnot.io",
"https://wotnot.io/pricing"
]
}Response
{
"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"
}
}
]
}{
"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"
]
}
]
}{
"message": "Please reach out to support to use this feature",
"ok": false,
"error": "UNAUTHORIZED_FEATURE",
"code": "UNAUTHORIZED_FEATURE",
"status": 401
}Adding domain data source to a knowledge base
POST /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
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"type": "domain",
"url": "https://wotnot.io",
"exclude_urls": "",
"refresh_frequency": null
}Response
{
"ok": true,
"domain_id": 8,
"request_id": "3QWuobWJE3jF065037422196qAdTZ2Ct"
}{
"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"
]
}
]
}{
"message": "Please reach out to support to use this feature",
"ok": false,
"error": "UNAUTHORIZED_FEATURE",
"code": "UNAUTHORIZED_FEATURE",
"status": 401
}Deleting data sources from a knowledge base
DELETE /v1/ai/knowledge-bases/<knowledge_base_id>/data-sources
Using this API, you can delete data sources from an existing knowledge base.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"data_sources": [
<data_source_id_1>,
<data_source_id_2>
]
}Response
{
"ok": true
}{
"error": "BAD_REQUEST",
"ok": false,
"status": 400,
"message": [
{
"message": "\"data_sources\" is required",
"path": [
"data_sources"
]
}
]
}{
"error": "UNAUTHORIZED",
"ok": false,
"status": 401,
"message": "Invalid token. Provide the valid account token."
}{
"message": "Resource not found",
"ok": false,
"error": "RESOURCE_NOT_FOUND",
"code": "RESOURCE_NOT_FOUND",
"status": 404
}Get training status of a data source
GET /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
Content-Type
application/json
Authorization
Bearer <token>
Body
source_ids
query params
Comma-separated list of data source IDs to be passed as query params.
Response
{
"sources": [
{
"id": 330778,
"name": "sample.txt",
"status": "in-progress",
"knowledge_base_id": 876
}
],
"ok": true
}{
"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!"
}Fetch knowledge base details
GET /v1/ai/knowledge-base/<knowledge_base_id>
Using this API, you can fetch knowledge base and it's relevant data sources details.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"limit": 100,
"offset": 1
}Response
{
"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"
}{
"ok": false,
"message": "Resource not found",
"error": "RESOURCE_NOT_FOUND",
"code": "RESOURCE_NOT_FOUND"
}Creating contacts
POST /v1/conversations
Using this endpoint, you can create new contacts and update existing contacts.
Headers
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.
{
"contacts": [
{
"name": "Michael Anderson",
"email": "[email protected]",
"phone": "+1212555",
"custom_variables": {
"company": "Example Company"
}
},
{
"name": "Jessica Martinez",
"email": "[email protected]",
"phone": "+111221555",
"custom_variables": {
"company": "Example Company"
}
}
]
}Response
{
"created": [
{
"id": 24135508,
"external_key": "111221555_13361",
"key": "6AFH8gyvwKCB073815082213IgPXtWMj",
"ok": true
}
],
"updated": [
{
"id": 24135493,
"external_key": "1212555_13361",
"key": "7oFMaCsVoDD2073727174868hp2AavON",
"ok": true
}
]
}{
"error": "BAD_REQUEST",
"ok": false,
"status": 400,
"message": [
{
"message": "\"contacts[0]\" must contain at least one of [email, phone]",
"path": [
"contacts",
0
]
}
]
}{
"error": "UNAUTHORIZED",
"ok": false,
"status": 401,
"message": "Invalid token. Provide the valid account token."
}Creating a conversation
POST /v1/conversations
Using this endpoint, you can start/create a new conversation.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
Contains the message payload. Payload differs based on channel.
{
"channel": "WHATSAPP",
"from": "1123123123",
"to": {
"phone": "11231231230",
"name": "John Doe",
"email": "[email protected]"
},
"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": "[email protected]"
}{
"channel": "SMS",
"from": "1-123-1231230",
"to": {
"phone": "1-1321231320",
"name": "John Doe",
"email": "[email protected]"
},
"message": {
"type": "text",
"text": "Hii"
},
"assignee": "[email protected]"
}Response
{
"ok": true,
"conversation": {
"id": "12wfegrgt4t",
"message_id": "sdvgret4353b",
"created_at": "",
"assignee": {
"id": 123,
"to": "[email protected]"
}
},
"contact": {
"id": "11111111",
"name": "John Doe",
"phone": "1234567890",
"email": "[email protected]"
}
}{
"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
}{
"error": "JWT_SIGNATURE_EXCEPTION",
"message": "Invalid JWT token",
"ok": false,
"status": 401
}{
"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
}Send agent response to a conversation
POST /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
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"message": {
"data": {
"body": "Hi"
},
"type": "text"
},
"user": {
"by": "[email protected]"
}
}{
"message": {
"file": {
"path": "https://framerusercontent.com/images/L2xfXiiCkddPZOjvWCGTusENwb4.png",
"size": 1,
"type": "image/png",
"name": "L2xfXiiCkddPZOjvWCGTusENwb4.png"
},
"type": "file"
},
"user": {
"by": "[email protected]"
}
}{
"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": "[email protected]"
}
}{
"message": {
"data": {
"template": "template_1"
},
"type": "template"
},
"user": {
"by": "[email protected]"
}
}Response
{
"ok": true,
"message_id": "6HRBshHEcV8P103039226478taGDJQxC"
}{
"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
}{
"ok": false,
"error": "JWT_SIGNATURE_EXCEPTION",
"code": "JWT_SIGNATURE_EXCEPTION",
"message": "Invalid JWT token",
"status": 401
}{
"ok": false,
"error": "CONVERSATION_NOT_FOUND",
"code": "CONVERSATION_NOT_FOUND",
"message": "Conversation is not available.",
"status": 404
}Closing a conversation
POST /api/v1/conversation/<conversation_id>/events
Use this endpoint to close an open conversation.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"event": "status",
"status": "CLOSE",
"user": {
"by": "[email protected]"
}
}Response
{
"ok": true
}{
"ok": false,
"error": "CONVERSATION_NOT_CLOSED",
"code": "CONVERSATION_NOT_CLOSED",
"message": "Conversation is not closed due to user limit validation.",
"status": 400
}{
"ok": false,
"error": "JWT_SIGNATURE_EXCEPTION",
"code": "JWT_SIGNATURE_EXCEPTION",
"message": "Invalid JWT token",
"status": 401
}{
"ok": false,
"error": "CONVERSATION_NOT_FOUND",
"code": "CONVERSATION_NOT_FOUND",
"message": "Conversation is not available.",
"status": 404
}Changing assignee in a conversation
POST /api/v1/conversation/<conversation_id>/events
Use this endpoint to change the assignee in an open conversation.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
// Change from assignee to assignee
{
"event": "assignee",
"user": {
"by": "[email protected]",
"to": "[email protected]"
}
}
// Change from assignee to team
{
"event": "assignee",
"team": {
"by": "[email protected]",
"to": "Sales"
}
}Response
{
"ok": true
}{
"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
}{
"ok": false,
"error": "JWT_SIGNATURE_EXCEPTION",
"code": "JWT_SIGNATURE_EXCEPTION",
"message": "Invalid JWT token",
"status": 401
}{
"ok": false,
"error": "CONVERSATION_NOT_FOUND",
"code": "CONVERSATION_NOT_FOUND",
"message": "Conversation is not available.",
"status": 404
}Update variable of a conversation
POST /v1/accounts/<account_id>/conversations/<conversation_id>/variables
Use this endpoint to update the variables in the conversation.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"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": "[email protected]"
}
]
}Response
{
"ok": true
}{
"ok": false,
"message": {
"variables": [
"Shorter than minimum length 1."
]
},
"status": 400,
"error": "BAD_REQUEST"
}{
"error": "UNAUTHORIZED",
"ok": false,
"status": 401,
"message": "Invalid token. Provide the valid account token."
}{
"message": "Conversation is not found",
"ok": false,
"error": "CONVERSATION_NOT_FOUND",
"code": "CONVERSATION_NOT_FOUND",
"status": 404
}Set webhook URL for Events feature
POST /v1/accounts/<account_id>/webhook
Use this endpoint to set webhook for receiving conversation related events from the account.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"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
{
"ok": true
}{
"error": "UNAUTHORIZED",
"ok": false,
"status": 401,
"message": "Invalid token. Provide the valid account token."
}Create a bot
POST /v1/bot
Using this API, you can create a bot in account.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"name": "BOT_NAME",
"template_id": REFERENCE_BOT_ID,
"channel": "API"
}Response
{
"ok": true,
"id": BOT_ID
}{
"ok": false,
"message": "Maximum bots limit reached for the account.",
"error": "MAXIMUM_BOTS_LIMIT_REACHED",
"code": "MAXIMUM_BOTS_LIMIT_REACHED"
}Fetch bot flow
GET /v1/bots/<bot_id>/flow
Using this API, you can fetch bot's flow data.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
Response
{
"ok": true,
"data": "BOT_FLOW_JSON",
"is_deployed": true,
"last_deployed_at": "2025-05-05 10:37:43.128000"
}{
"error": "BOT_NOT_FOUND",
"ok": false,
"status": 404,
"message": "Bot not found."
}Deploy bot flow
POST /v1/bots/<bot_id>/deploy
Using this API, you can deploy the bot flow after modifying it's JSON data.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
{
"flow_diagram": "BOT_FLOW_JSON"
}Response
{
"ok": true,
"data": "BOT_FLOW_JSON",
"is_deployed": true,
"last_deployed_at": "2025-05-05 10:37:43.128000"
}{
"error": "BOT_NOT_FOUND",
"ok": false,
"status": 404,
"message": "Bot not found."
}Fetch Bots List
GET /v1/accounts/<account_id>/bots
Use this endpoint to fetch list of bots available in the account.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Response
{
"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": "[email protected]"
}
"created_at": "2024-02-09 10:59:13.783000",
"preview_key": "6H7PD4WwTmsU105913782825Zk3KCj3t",
"bot_id": 9633
}
]
}{
"error": "UNAUTHORIZED",
"ok": false,
"status": 401,
"message": "Invalid token. Provide the valid account token."
}Last updated
Was this helpful?