> For the complete documentation index, see [llms.txt](https://docs.taptalk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taptalk.io/sendtalk-api-documentation/messages-api.md).

# Messages API

### Send Message API

## Send Message

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark>       | string | The recipient number (example: 62811001234)                                                                                                                                                                                                   |
| messageType<mark style="color:red;">\*</mark> | string | <p>The message type<br>Values: <code>"otp"</code>, <code>"text"</code>, <code>"image"</code> <br>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</p> |
| body<mark style="color:red;">\*</mark>        | 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")                                                                                                                                                                                                |

{% tabs %}
{% tab title="200 Successfully add the message to the queue" %}

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

{% endtab %}

{% tab title="400 The request validation is failed" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Message Types** \
The difference between **`OTP`** type and **`TEXT`** type is based on the **queue of our system**. The message wit&#x68;**`OTP`**&#x74;ype will be **prioritized** **first** than the other type in sending the message.
{% endhint %}

{% hint style="warning" %}
**Important**\
Do not forget to add **API-Key** in Headers and make sure the **Body** **Parameters** type is **JSON**
{% endhint %}

#### Request <a href="#request" id="request"></a>

| Field               | Type   | Description                                                                                                   |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| phone               | string | The phone number to send the message to.                                                                      |
| messageType         | string | <p>The message type.</p><p>Allowed values: <code>"otp"</code>, <code>"text"</code>, <code>"image".</code></p> |
| 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:

{% code title="TEXT" %}

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

{% endcode %}

{% code title="IMAGE" %}

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

```

{% endcode %}

![](/files/-MdS1VPMsBV6wsAgs9bq)

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

{% code title="Success Response" %}

```json
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"
  }
}
```

{% endcode %}

#### Response Error 4xx

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

{% code title="ParamValidationFailed" %}

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

{% endcode %}

{% code title="HeaderValidationFailed" %}

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

{% endcode %}

### Get Send Status API

## Get Status Message

<mark style="color:green;">`POST`</mark> `https://sendtalk-api.taptalk.io/api/v1/message/get_status`

Get the status of a message.

#### Headers

| Name                                      | Type   | Description                                    |
| ----------------------------------------- | ------ | ---------------------------------------------- |
| API-Key<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark> | string | The message ID. |

{% tabs %}
{% tab title="200 Successfully get the send status of the message the queue" %}

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

{% endtab %}

{% tab title="400 The request validation is failed" %}

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

{% endtab %}

{% tab title="404: Not Found " %}

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Important**\
Do not forget to add **API-Key** in Headers and make sure the **Body** **Parameters** type is **JSON**
{% endhint %}

#### Request <a href="#request" id="request"></a>

| Field | Type   | Description            |
| ----- | ------ | ---------------------- |
| id    | string | The ID of the message. |

Below is the example of the request:

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

![](/files/iLLuRbyQ23476DxIT5kW)

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

{% code title="Success Response" %}

```json
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
  }
}
```

{% endcode %}

#### Response Error 4xx

<table><thead><tr><th width="368.5">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>ParamValidationFailed</code></td><td>The parameter validation failed.</td></tr><tr><td><code>ItemNotFound</code></td><td>The message ID is not found.</td></tr><tr><td><code>HeaderValidationFailed</code></td><td>The request header validation failed.</td></tr></tbody></table>

{% code title="ParamValidationFailed" %}

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

{% endcode %}

{% code title="ItemNotFound" %}

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

{% endcode %}

{% code title="HeaderValidationFailed" %}

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

{% endcode %}