Inbox API

The set of methods that can be used when for OneTalk Inbox

Send Message via WhatsApp

POST https://onetalk-api.taptalk.io/api/integration/v1/inbox/send_message_whatsapp

Send a message to the specified phone number via WhatsApp channel. The phone number must be registered in WhatsApp. If parameter withCase is true, the message will always be sent to an open case. If the user already has an open case, the message will be sent to that case. Otherwise, a new case will be created for the user.

Headers

Name	Type	Description
API-Key*	string	API key for accessing the API.
Content-Type	string	Content type of the request body.
User-Agent	string	The user agent of the client accessing the API.

Request Body

Name	Type	Description
channelID	string	The channel ID.
phone	string	The phone number to send the message to.
messageType	string	The message type. Allowed values: text, image, file
body	string	The message body (text message or file URL).
filename	string	The name of the file (required for message type other than "text").
caption	string	The caption, if any (for message type "image").
withCase	boolean	If true, the message will be sent to the recipient's existing open case or a new case will be created.
topicID	integer	The topic ID for new case.

200 Response Success

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The message has been added to queue",
    "caseID": "96212160DF"
  }
}

400 Error 4xx (ParamValidationFailed, HeaderValidationFailed, TierNotSelected)

40002 (ParamValidationFailed): The parameter validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Channel ID is required",
    "field": "channelID"
  },
  "data": {}
}

40002 (HeaderValidationFailed): The request header validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

49900 (TierNotSelected): The organization has not selected the tier.
HTTP/1.1 200 OK
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}

Click the right arrow above on the right side of Sync User Contact API to see the full list of request parameters and the response.

Channel ID can be obtained in OneTalk Dashboard Go to Integration and click WhatsApp for SME, then click the channel detail and you can copy the Channel ID

Request Example (text)

{
    "channelID": "2101081881",
    "phone": "6281212345678",
    "messageType": "text",
    "body": "Hi, this is a message.",
    "withCase": true,
    "topicID": 1
}

Request Example (image)

{
    "channelID": "2101081881",
    "phone": "6281212345678",
    "messageType": "image",
    "body": "http://www.example.com/chat/file/image/008dce72-06c0?token=802714",
    "filename": "my-photo.jpg",
    "caption": "This is the photo.",
    "withCase": true,
    "topicID": 1
}

Request Example (file)

{
    "channelID": "2101081881",
    "phone": "6281212345678",
    "messageType": "file",
    "body": "http://www.example.com/chat/file/008dce72-06c0.pdf",
    "filename": "Test.pdf",
    "caption": "",
    "withCase": false,
    "topicID": 1
}

Send Templated Message via WhatsApp Business API

POST https://onetalk-api.taptalk.io/api/integration/v1/inbox/send_templated_message_whatsappba

Send a templated message to the specified phone number via a WhatsApp Business API channel. The phone number must be registered in WhatsApp. If parameter withCase is true, the message will always be sent to an open case. If the user already has an open case, the message will be sent to that case. Otherwise, a new case will be created for the user.

Headers

Name	Type	Description
API-Key*	string	API key for accessing the API
Content-Type	string	Content type of the request body.
User-Agent	string	The user agent of the client accessing the API.

Request Body

Name	Type	Description
channelID*	string	The channel ID.
phone*	string	The phone number to send the message to.
templateName*	string	The message template name.
languageCode*	string	The language code of the template message.
parameters	object	Parameters for the message template.
header	array	Parameters for template header.
name	string	Name of the parameter.
value	string	Value of the parameter.
body	array	Parameters for template body.
name	string	Name of the parameter.
value	string	Value of the parameter.
footer	array	Parameters for template footer.
name	string	Name of the parameter.
value	string	Value of the parameter.
withCase	boolean	If true, the message will be sent to the recipient's existing open case or a new case will be created.
phoneNumberID*	string	The phone number ID to send the message from.
buttons	array	Parameters for template buttons.
name	string	Name of the parameter.
value	string	Value of the parameter.
topicID	integer	The topic ID for new case.

200

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The message has been added to queue",
    "caseID": "96212160DF"
  }
}

400 40002 (ParamValidationFailed): The parameter validation failed. 40002 (HeaderValidationFailed): The request header validation failed. 49900 (TierNotSelected): The organization has not selected the tier.

HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Channel ID is required",
    "field": "channelID"
  },
  "data": {}
}


HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}


HTTP/1.1 200 OK
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}

Click the right arrow above on the right side of Sync User Contact API to see the full list of request parameters and the response.

Channel ID can be seen in OneTalk Dashboard Go to Integration and click WhatsApp Business API, then click the channel detail and you can copy the Channel ID

Request Example

{
  "channelID": "2100480937",
  "phoneNumberID": "103011859190563",
  "phone": "6281212345678",
  "templateName": "greetings_v1",
  "languageCode": "en",
  "parameters": {
    "header": [
      //Text Template Type, Header with Variable
      {
        "name": "variable_name",
        "value": "Good Morning"
      },
      //Dynamic Media Template Type, Media Type "Document"
      {
        "name": "document",
        "value": "https://taptalk.io/file_path_url.pdf"
      },
      //Dynamic Media Template Type, Media Type "Image"
      {
        "name": "image",
        "value": "https://taptalk.io/file_path_url.pdf"
      },
      //Dynamic Media Template Type, Media Type "Video"
      {
        "name": "video",
        "value": "https://taptalk.io/file_path_url.pdf"
      },
    ],
    "body": [
      {
        "name": "name",
        "value": "John"
      },
      {
        "name": "office_hours",
        "value": "09:00 - 17:00"
      }
    ],
    "footer": [],
    "buttons": [
      {
        "name": "url_0",
        "value": "1d-1"
      }
    ]
  },
  "withCase": true,
  "topicID": 1
}

Get Updated Case List

GET https://onetalk-api.taptalk.io/api/integration/v1/inbox/case/get_updated_list

Get the list of new and updated cases since since_timestamp.

Headers

Name	Type	Description
API-Key*	string	API key for accessing the API
Content-Type	string	Content type of the request body.
User-Agent	string	The user agent of the client accessing the API.

Request Body

Name	Type	Description
since_timestamp *	long	Timestamp in Unix milliseconds to start getting the updates from.
limit	integer	Maximum number of items to retrieve. Default value: 100 Size range: 1..100

200: OK Response Success

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "cases": [
      {
        "id": "00C49D438C",
        "contact": {
          "id": "76379c2a-14b7-4c88-88c7-17244be50acf",
          "fullName": "Jony XL",
          "alias": "",
          "email": "",
          "phone": "6287776325008",
          "agentRemark": "",
          "createdTime": 1587352926788,
          "updatedTime": 0
        },
        "agent": {
          "email": "[e-mail]",
          "fullName": "Jony"
        },
        "firstMessage": "1",
        "isClosed": false,
        "isJunk": false,
        "agentRemark": "",
        "createdTime": 1587352928385,
        "updatedTime": 1640367746510
      }
    ],
    "hasMore": false,
    "lastTimestamp": 1640367746510
  }
}

400: Bad Request Error 4xx (ParamValidationFailed, HeaderValidationFailed, TierNotSelected)

40002 (ParamValidationFailed): The parameter validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Since timestamp is invalid",
    "field": "since_timestamp"
  },
  "data": {}
}

40002 (HeaderValidationFailed): The request header validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

49900 (TierNotSelected): The organization has not selected the tier.
HTTP/1.1 200 OK
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}

Click the right arrow above on the right side of Get Updated Case List API to see the full list of request parameters and the response.

Request Example

?since_timestamp=1640367001000&limit=100

Response Example

{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "cases": [
      {
        "id": "00C49D438C",
        "contact": {
          "id": "76379c2a-14b7-4c88-88c7-17244be50acf",
          "fullName": "John Doe",
          "alias": "",
          "email": "",
          "phone": "628123456789",
          "agentRemark": "",
          "createdTime": 1587352926788,
          "updatedTime": 0
        },
        "agent": {
          "email": "[e-mail]",
          "fullName": "Agent"
        },
        "firstMessage": "1",
        "isClosed": false,
        "isJunk": false,
        "agentRemark": "",
        "createdTime": 1587352928385,
        "updatedTime": 1640367746510
      }
    ],
    "hasMore": false,
    "lastTimestamp": 1640367746510
  }
}

Success 200 Field Description

Update Case

POST https://onetalk-api.taptalk.io/api/integration/v1/inbox/case/update

Update a case details. Only specify parameter for fields to be updated.

Headers

Name	Type	Description
API-Key*	string	API key for accessing the API
Content-Type	string	Content type of the request body.
User-Agent	string	The user agent of the client accessing the API.

Request Body

Name	Type	Description
caseID*	string	The case id.
agentRemark	string	Agent's Remark for the case, may be empty.
isJunk	boolean	If the case is junk.

Request Example

{
    "caseID": "00C49D438C",
    "agentRemark": "...",
    "isJunk": true
}

200 Success Response

Field	Type	Description
success	boolean	If updated successfully.
message	string	The message.

200 Success Response

{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "Case updated successfully",
  }
}

4xx Error Response

Name	Description
ParamValidationFailed	The parameter validation failed.
FeatureNotAvailable	The feature is not available due to the organization's current tier.
HeaderValidationFailed	The request header validation failed.
TierNotSelected	The organization has not selected a tier.

ParamValidationFailed

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Case ID is required",
    "field": "caseID"
  },
  "data": {}
}

FeatureNotAvailable

{
  "status": 499,
  "error": {
    "code": "49901",
    "message": "This feature is not available for your current tier",
    "field": ""
  },
  "data": {}
}

HeaderValidationFailed

{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

TierNotSelected

{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}