# Message

{% hint style="warning" %}
**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.
{% endhint %}

### 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.

{% hint style="warning" %}
**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.
{% endhint %}

**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.             |

{% tabs %}
{% tab title="POST" %}

```php
BASE_URL/v1/server/message/send/custom

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

{% endtab %}
{% endtabs %}

### 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.                      |

{% hint style="info" %}
**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.
{% endhint %}

{% tabs %}
{% tab title="Request Example (Personal)" %}

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

{% endtab %}

{% tab title="Request Example (Group)" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request Example (With Image)" %}

```javascript
{
    "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": ""
}
```

{% endtab %}
{% endtabs %}

### Success 200

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

{% tabs %}
{% tab title="Success Response" %}

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

{% endtab %}
{% endtabs %}

### Error 4xx

| **Name**               | **Description**                       |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| HeaderValidationFailed | The request header validation failed. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="HeaderValidationFailed" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.taptalk.io/powertalk-chat-sdk-documentation/powertalk-server-api/message.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.