Messages API

This page is used to implement SendTalk messages APIs, please refer to these following APIs

Send Message API

Send Message

POST https://sendtalk-api.taptalk.io/api/v1/message/send_whatsapp

Send a message to the specified number via WhatsApp

Headers

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

Request Body

Name	Type	Description
phone*	string	The recipient number (example: 62811001234)
messageType*	string	The message type Values: "otp", "text", "image" Use OTP to send a message related to OTP, or you can use type text or image to send a message or notification that is not related to OTP
body*	string	The message body (text message or file URL for the image)
filename	string	The name of the file (required for all message type, except for "text")
caption	string	The caption, if any (for message type "image")

200 Successfully add the message to the queue

{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The message has been added to queue",
    "reason": "",
    "id": "f26ccf7a-d867-b3a4-d333-117ec668718d"
  }
}

400 The request validation is failed

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

// Failed to validate request body
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Phone is required",
    "field": "phone"
  },
  "data": {}
}

Message Types The difference between OTP type and TEXT type is based on the queue of our system. The message withOTPtype will be prioritized first than the other type in sending the message.

Important Do not forget to add API-Key in Headers and make sure the Body Parameters type is JSON

Request

Field	Type	Description
phone	string	The phone number to send the message to.
messageType	string	The message type. Allowed values: "otp", "text", "image".
body	string	The message body (text message or file URL).
fileName (optional)	string	The name of the file (required for message type other than "otp" and "text").
caption (optional)	string	The caption, if any (for message type "image").

Below is the example of the request:

TEXT

{
    "phone": "6281212345678",
    "messageType": "text",
    "body": "Hi this is a message"
}

IMAGE

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

Response Success 200

Field	Type	Description
success	boolean	If message is sent successfully.
message	string	The success or error message.
reason	string	Failure reason ("invalid_recipient", "insufficient_balance").
id	string	The message ID, if successful.

Success Response

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The message has been added to queue",
    "reason": "",
    "id": "f26ccf7a-d867-b3a4-d333-117ec668718d"
  }
}

Response Error 4xx

Name	Description
ParamValidationFailed	The parameter validation failed.
HeaderValidationFailed	The request header validation failed.

ParamValidationFailed

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

HeaderValidationFailed

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

Get Send Status API

Get Status Message

POST https://sendtalk-api.taptalk.io/api/v1/message/get_status

Get the status of a message.

Headers

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

Request Body

Name	Type	Description
id*	string	The message ID.

200 Successfully get the send status of the message the queue

{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "status": "sent",
    "isPending": false,
    "isSent": true,
    "sentTime": 1635774548482,
    "currency": "IDR",
    "price": 100,
    "createdTime": 1635774547004
  }
}

400 The request validation is failed

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

// Failed to validate request body
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Message ID is required",
    "field": "phone"
  },
  "data": {}
}

404: Not Found

// Item Not Found
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Message is not found",
    "field": ""
  },
  "data": {}
}

Important Do not forget to add API-Key in Headers and make sure the Body Parameters type is JSON

Request

Field	Type	Description
id	string	The ID of the message.

Below is the example of the request:

{
    "id": "3f581b4e-8e7c-4ebf-a533-39115737b81c"
}

Response Success 200

Field	Type	Description
status	string	The message status
isPending	boolean	If the message is pending
isSent	boolean	If the message has been sent to the channel
sentTime	long	The time the message was sent, in Unix milliseconds
currency	string	The currency
price	long	The charged price
createdTime	long	The time the message was created, in Unix milliseconds

Success Response

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "status": "sent",
    "isPending": false,
    "isSent": true,
    "sentTime": 1635774548482,
    "currency": "IDR",
    "price": 100,
    "createdTime": 1635774547004
  }
}

Response Error 4xx

Name	Description
ParamValidationFailed	The parameter validation failed.
ItemNotFound	The message ID is not found.
HeaderValidationFailed	The request header validation failed.

ParamValidationFailed

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

ItemNotFound

HTTP/1.1 200 OK
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Message is not found",
    "field": ""
  },
  "data": {}
}

HeaderValidationFailed

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