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

![](https://4266585843-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LfVupFSqh_qZAY9OiCO%2F-MdS1756tCosCQ_D3bMM%2F-MdS1VPMsBV6wsAgs9bq%2FScreen%20Shot%202021-06-30%20at%2020.06.54.png?alt=media\&token=de7139cd-10e4-4555-982d-2c9a4b770f6d)

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

![](https://4266585843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LfVupFSqh_qZAY9OiCO%2Fuploads%2FFVF0JsfjNj8ohWOAxV52%2FScreen%20Shot%202021-11-04%20at%2010.17.54.png?alt=media\&token=6e77d0f1-6d74-4787-9f9a-e38f0f40640e)

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


---

# 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/sendtalk-api-documentation/messages-api.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.