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.

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

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.

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.

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

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

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

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

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

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.

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.

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

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

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

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

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`

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

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": "jony@taptalk.io",
          "fullName": "Jony"
        },
        "firstMessage": "1",
        "isClosed": false,
        "isJunk": false,
        "agentRemark": "",
        "createdTime": 1587352928385,
        "updatedTime": 1640367746510
      }
    ],
    "hasMore": false,
    "lastTimestamp": 1640367746510
  }
}

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.

?since_timestamp=1640367001000&limit=100

{
  "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": "agent@taptalk.io",
          "fullName": "Agent"
        },
        "firstMessage": "1",
        "isClosed": false,
        "isJunk": false,
        "agentRemark": "",
        "createdTime": 1587352928385,
        "updatedTime": 1640367746510
      }
    ],
    "hasMore": false,
    "lastTimestamp": 1640367746510
  }
}

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.

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.

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.

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

200 Success Response

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

Field

Type

Description

success

boolean

If updated successfully.

message

string

The message.

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

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.

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

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

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

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

PreviousIntegration API NextUser/Contact API

Last updated 7 months ago