Message

IMPORTANT!

Server Key ID and Server Key Secret will be used to construct a request and add as a HTTP Header. To construct a request, please format your generated Server Key ID and Server Key Secret and wrap it to Base64, so the format will be like this:

encodeToBase64(SERVER_KEY_ID:SERVER_KEY_SECRET) *don't forget to add colon (:) between Server Key ID and Server Key Secret

Then, put the base64 string on your HTTP Header Field with key “Server-Key” and then construct URL request and parameter for the request.

Send Custom Message

Send custom message on behalf of a user to another user.

The following message types are supported:

ID	Description
1001	text
1002	image
2001	products

Other than message types listed above, all custom message types are supported with values of "3xxx" as self-defined by the customer.

IMPORTANT!

If the body or data is too long, the message might be split into multiple messages and sent separately. In case the filterID is not empty, only the last one of the split messages will be visible.

Body & Data Payload The following document describes payload details for data of a message.

For the body, it should only contain text as it is also used as push notification's content.

Note that message's data is always string regardless of the message type, and usually contains JSON string.

1001 - text The data should be empty.

1002 - image The data contains JSON string for the images' details. A message can contain an array of one or more images, each with the following attributes.

Key	Type	Description
url	string	The image URL, to download the image.
mediaType	string	The media type (e.g.: "image/jpeg").
size	integer	The image's size, in bytes.
width	integer	The image's width, in pixels.
height	integer	The image's height, in pixels.
caption	string	The image caption.

2001 - products The data contains JSON string for the products' details. A message can contain an array of one or more products, each with the following attributes.

Key	Type	Description
name	string	The product's name.
imageURL	string	The product's image URL.
description	string	The product's description.
price	string	The price.
currency	string	The price's currency.
rating	string	The product's rating, may be empty.
buttonOption1Text	string	The 1st button's text.
buttonOption1Color	string	The 1st button's color.
buttonOption2Text	string	The 2nd button's text.
buttonOption2Color	string	The 2nd button's color.

POST

BASE_URL/v1/server/message/send/custom

example:
https://taptalk.io/v1/server/message/send/custom

Request

Field	Type	Description
body	string	(104) The text message.
data (optional)	string	(105) The data payload, based on the message type.
filterID (optional)	string	(106) The filter ID.
senderXCUserID	string	(107) The sender's XC user ID.
recipientXCUserID (optional)	string	(108) The recipient's XC user ID.
xcRoomID (optional)	string	(109) The room ID to send to.

Note

Can't use both recipientXCUserID and xcRoomID parameters at the same time in one request. Use recipientXCUserID for sending to personal room type and xcRoomID for sending to other room type.

Request Example (Personal)

{
    "messageType": 1001,
    "body": "Hi, nice to meet you.",
    "data": "",
    "filterID": "",
    "senderXCUserID": "1",
    "recipientXCUserID": "6",
    "xcRoomID": ""
}

Request Example (Group)

{
    "messageType": 1001,
    "body": "Hi, nice to meet you.",
    "data": "",
    "filterID": "",
    "senderXCUserID": "1",
    "recipientXCUserID": "",
    "xcRoomID": "6A02C41D"
}

Request Example (With Image)

{
    "messageType": 1002,
    "body": "Image",
    "data": "{\"url\":\"http://www.example.com/img/50a09c1b.jpg\",\"mediaType\":\"image/jpeg\",\"size\":131072,\"width\":1280,\"height\":720,\"caption\":\"Look at this picture!\"}",
    "filterID": "products:expert:1",
    "senderXCUserID": "1",
    "recipientXCUserID": "6",
    "xcRoomID": ""
}

Success 200

Field	Type	Description
success	boolean	If the request is successful.
localID	string	The local IDs of the sent message.

Success Response

{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "localID": "Uepo3yojSYH4j0rxf8TbMPexgm12k2js"
  }
}

Error 4xx

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

ParamValidationFailed

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'contacts' cannot be empty",
    "field": "101"
  },
  "data": {}
}

HeaderValidationFailed

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