Talk to Sales: +91 9555-396-396

For Support: +91 80-1055-1055

Chat ON Desk API Documentation

HTTP Status Codes

Chat ON Desk uses standard HTTP status codes to communicate errors:

Status Code	Description
200	OK – Everything went as planned.
202	Accepted – Request accepted.
400	Bad Request – Something was malformed.
401	Unauthorized – Credentials missing/invalid.
402	Payment Required – Plan/usage exceeded.
403	Forbidden – Valid credentials but no access.
404	Not Found – Object doesn’t exist.
409	Conflict – Resource update conflict.
429	Too Many Requests – Rate limit exceeded.
5xx	Server Errors – Something went wrong.

Send Message (Template)

POST: https://app.chatondesk.com/api/structuredpush.json

Parameter	Description
`apikey`	API Key generated from your SMS account (required)
`structureid`	Unique id generated for your structured template (required)
`channel`	Channel, e.g., `whatsapp` (required)
`type`	Message type, e.g., `template` (required)
`phone`	Destination mobile number (with or without country code). Multiple numbers allowed, comma separated. (required)
`data`	Template variables in JSON format (optional)

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/api/structuredpush.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "structureid": "25",
  "phone": "+918010551055",
  "channel": "whatsapp",
  "type": "template",
  "data": {
    "mobile": "8010551055",
    "name": "John Doe"
  }
}'

Response

{
  "status": "success",
  "description": "Template message sent successfully"
}

Send Message (Custom Message)

POST: https://app.chatondesk.com/api/structuredpush.json

Parameter	Description
`apikey`	API Key generated from your SMS account
`phone`	Mobile number(s) to send SMS (with or without country code, multiple numbers comma separated)
`channel`	Chatondesk channel (e.g., `whatsapp`)
`type`	`message`
`message`	Custom SMS content

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/api/structuredpush.json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "apikey": "63b03725e6646",
    "phone": "+918010551055",
    "channel": "whatsapp",
    "type": "message",
    "message": "test sms"
}'

Response

200 - OK
{
    "status": "success",
    "description": "successfully sent"
}

Create Profile

POST: https://app.chatondesk.com/chatbot/api/createprofile.json

Parameter Description

apikey API Key generated from your SMS account

datas

JSON object containing profile details:

{
  "name": "test user",
  "email": "[email protected]",
  "phone": "8010551055",
  "bot_id": "70d19fce-bd56-11e7-97b0-eca86b71XXXX",
  "Chatuserchennelid": ["whatsapp","smsalert"]
}

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/createprofile.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "datas": {
    "name": "test user",
    "email": "[email protected]",
    "phone": "8010551055",
    "bot_id": "70d19fce-bd56-11e7-97b0-eca86b71XXXX",
    "Chatuserchennelid": ["whatsapp","smsalert"]
  }
}'

Response

200 - OK
{
  "status": "success",
  "description": "Profile has been created successfully",
  "profile_id": "12410"
}

Chat History

GET: https://app.chatondesk.com/chatbot/api/chathistory.json

Parameter	Description
`apikey`	API Key generated from your SMS account
`profile_id`	Profile Id
`page`	Page number (default = `1`)
`limit`	Number of records per page (default = `10`)
`order`	Sorting order (`asc` / `desc`)

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/chathistory.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "profile_id": "34",
  "limit": "10",
  "page": "1",
  "order": "desc"
}'

Response

200 - OK
{
  "status": "success",
  "description": [
    {
      "Chatlog": {
        "input": "",
        "response": "[{\"type\":\"text\",\"message\":\"hi\"}]",
        "date": "2025-02-28 18:28:40"
      },
      "Channel": {
        "system_name": "website"
      },
      "Profile": []
    }
  ]
}

Get Templates List

GET: https://app.chatondesk.com/chatbot/api/templatelist.json

Parameter	Description
`apikey`	API Key generated from your SMS account
`limit`	Number of templates to retrieve (e.g., `10`)
`searchname`	Search filter for template name (e.g., `test`)

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/templatelist.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "limit": "10",
  "searchname": "test"
}'

Response

200 - OK
{
  "status": "success",
  "description": "successfully sent"
}

Get Channels List

GET: https://app.chatondesk.com/chatbot/api/channellist.json

Parameter	Description
`apikey`	API Key generated from your SMS account

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/channellist.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646"
}'

Response

200 - OK
{
  "status": "success",
  "description": [
    {
      "Structuredtemplate": {
        "id": "7985848",
        "name": "dynamic image",
        "template": "{\"header\":{\"file_type\":\"dynamic\",\"type\":\"image\",\"name\":\"\",\"message\":\"##file##\",\"fallbackdata\":\"image\"},\"body\":{\"message\":\"Hello ##name##, thank you for contacting us. ##test##\"}}"
      }
    }
  ]
}

Generate OTP

POST: https://app.chatondesk.com/chatbot/api/mverify.json

Parameter	Description
`apikey`	API Key generated from your SMS account
`structureid`	Unique ID generated for your structured template
`channel`	Chatondesk channel (e.g., `whatsapp`)
`type`	`template` (message type)
`phone`	Mobile number(s) to send OTP (with/without country code, multiple comma separated)

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/mverify.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "structureid": "54",
  "phone": "+918010551055",
  "channel": "whatsapp",
  "type": "template"
}'

Response

200 - OK
{
  "status": "success",
  "description": "successfully sent"
}

Validate OTP

POST: https://app.chatondesk.com/chatbot/api/mverify.json

Parameter	Description
`apikey`	API Key generated from your SMS account
`channel`	Chatondesk channel (e.g., `whatsapp`)
`phone`	Mobile number(s) (with/without country code, multiple comma separated)
`code`	OTP entered by the user

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/mverify.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "phone": "+918010551055",
  "channel": "whatsapp",
  "code": "3167"
}'

Response

200 - OK
{
  "status": "success",
  "description": "Code does not match."
}

Get Reminder

GET: https://app.chatondesk.com/chatbot/api/reminderlist.json

Parameter	Description
`apikey`	API Key generated from your SMS account
`channel`	Chatondesk channel (e.g., `whatsapp`)
`phone`	Mobile number(s) (with/without country code, multiple comma separated)
`code`	OTP entered by the user

Request

Response

Request

curl --location --request GET 'https://app.chatondesk.com/chatbot/api/reminderlist.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "profile_id": "34",
  "id": "7",
  "limit": "10",
  "page": "1",
  "order": "desc"
}'

Response

200 - OK
{
  "status": "success",
  "description": [
    {
      "id": "7",
      "profile_id": "34",
      "reminder_text": "Your scheduled reminder message",
      "created_at": "2025-08-20 12:45:00"
    }
  ]
}

Create Reminder

POST: https://app.chatondesk.com/chatbot/api/createreminder.json

Parameter	Description
`apikey`	API Key generated from your SMS account (required)
`profile_id`	Profile Id (required)
`message`	Reminder content (required)
`time`	Date & time for schedule (Format: `YYYY-MM-DD HH:MM:SS`)
`sent_to`	Optional: `user` (specified user), `self` (current user)
`status`	Optional: `active`, `completed`, `canceled`
`type`	Optional: `one-time` or `recurring`
`frequency`	For recurring reminders: `daily`, `weekly`, `monthly`, `yearly`
`value`	Repetition value (e.g., `1,2,3`)
`endtime`	End date & time for recurring schedule (`YYYY-MM-DD HH:MM:SS`)

Request

Response

Request

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/createreminder.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "profile_id": "34",
  "message": "Test",
  "time": "2025-03-02 16:13:05",
  "sent_to": "user",
  "status": "active",
  "type": "recurring",
  "frequency": "daily",
  "value": "1",
  "endtime": "2025-03-05 16:13:05"
}'

Response

200 - OK
{
  "status": "success",
  "description": "Reminder created successfully",
  "reminder_id": "101"
}

Update Reminder

POST: https://app.chatondesk.com/chatbot/api/updatereminder.json

Parameter	Description
`apikey`	API Key generated from your SMS account (required)
`id`	Reminder Id (required)
`message`	Optional reminder content
`time`	Optional: Updated date & time (`YYYY-MM-DD HH:MM:SS`)
`sent_to`	Optional: `user` (specified user), `self` (current user)
`status`	Optional: `active`, `completed`, `canceled`
`type`	Optional: `one-time` or `recurring`
`frequency`	Optional: `daily`, `weekly`, `monthly`, `yearly`
`value`	Optional: repetition value (e.g., `1,2,3`)
`endtime`	Optional: end date & time (`YYYY-MM-DD HH:MM:SS`)

Request

Response

Request

Example Request (cURL)

curl --location --request POST 'https://app.chatondesk.com/chatbot/api/updatereminder.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "apikey": "63b03725e6646",
  "id": "7",
  "message": "Updated Test Reminder",
  "time": "2025-03-02 16:13:05",
  "sent_to": "user",
  "status": "active",
  "type": "recurring",
  "frequency": "daily",
  "value": "1",
  "endtime": "2025-03-05 16:13:05"
}'

Response

200 - OK
{
  "status": "success",
  "description": "Reminder updated successfully",
  "reminder_id": "7"
}