# Inbox API

## Send Message via WhatsApp

<mark style="color:green;">`POST`</mark> `https://onetalk-api.taptalk.io/api/integration/v1/inbox/send_message_whatsapp`

Send a message to the specified phone number via WhatsApp channel.\
\
The phone number must be registered in WhatsApp.\
\
If parameter **`withCase`** is true, the message will always be sent to an open case. If the user already has an open case, the message will be sent to that case. Otherwise, a new case will be created for the user.

#### Headers

| Name                                      | Type   | Description                                     |
| ----------------------------------------- | ------ | ----------------------------------------------- |
| API-Key<mark style="color:red;">\*</mark> | string | API key for accessing the API.                  |
| Content-Type                              | string | Content type of the request body.               |
| User-Agent                                | string | The user agent of the client accessing the API. |

#### Request Body

| Name        | Type    | Description                                                                                                                                             |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channelID   | string  | The channel ID.                                                                                                                                         |
| phone       | string  | The phone number to send the message to.                                                                                                                |
| messageType | string  | <p>The message type.<br>Allowed values: <strong><code>text</code></strong>, <strong><code>image</code></strong>, <strong><code>file</code></strong></p> |
| body        | string  | The message body (text message or file URL).                                                                                                            |
| filename    | string  | The name of the file (required for message type other than "text").                                                                                     |
| caption     | string  | The caption, if any (for message type "image").                                                                                                         |
| withCase    | boolean | If true, the message will be sent to the recipient's existing open case or a new case will be created.                                                  |
| topicID     | integer | The topic ID for new case.                                                                                                                              |

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

```json
HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The message has been added to queue",
    "caseID": "96212160DF",
    "trxID": "7f1007bf-d04b-4e83-9b2e-e193d3833ba1"
  }
}
```

{% endtab %}

{% tab title="400 Error 4xx (ParamValidationFailed, HeaderValidationFailed, TierNotSelected)" %}

```
40002 (ParamValidationFailed): The parameter validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Channel ID is required",
    "field": "channelID"
  },
  "data": {}
}

40002 (HeaderValidationFailed): The request header validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

49900 (TierNotSelected): The organization has not selected the tier.
HTTP/1.1 200 OK
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Click the <mark style="background-color:orange;">**right arrow**</mark> above on the right side of Sync User Contact API to see the full list of request parameters and the response.
{% endhint %}

{% hint style="warning" %}
**Channel ID** can be obtained in [OneTalk Dashboard](https://onetalk.taptalk.io)\
Go to **Integration** and click **WhatsApp for SME**, then click the channel detail and you can copy the **Channel ID**&#x20;
{% endhint %}

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

```go
{
    "channelID": "2101081881",
    "phone": "6281212345678",
    "messageType": "text",
    "body": "Hi, this is a message.",
    "withCase": true,
    "topicID": 1
}
```

{% endtab %}

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

```go
{
    "channelID": "2101081881",
    "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.",
    "withCase": true,
    "topicID": 1
}
```

{% endtab %}

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

```javascript
{
    "channelID": "2101081881",
    "phone": "6281212345678",
    "messageType": "file",
    "body": "http://www.example.com/chat/file/008dce72-06c0.pdf",
    "filename": "Test.pdf",
    "caption": "",
    "withCase": false,
    "topicID": 1
}
```

{% endtab %}
{% endtabs %}

## Send Templated Message via WhatsApp Business API

<mark style="color:green;">`POST`</mark> `https://onetalk-api.taptalk.io/api/integration/v1/inbox/send_templated_message_whatsappba`

Send a templated message to the specified phone number via a WhatsApp Business API channel.\
\
The phone number must be registered in WhatsApp.\
\
If parameter **`withCase`** is true, the message will always be sent to an open case. If the user already has an open case, the message will be sent to that case. Otherwise, a new case will be created for the user.

#### Headers

| Name                                      | Type   | Description                                     |
| ----------------------------------------- | ------ | ----------------------------------------------- |
| API-Key<mark style="color:red;">\*</mark> | string | API key for accessing the API                   |
| Content-Type                              | string | Content type of the request body.               |
| User-Agent                                | string | The user agent of the client accessing the API. |

#### Request Body

| Name                                            | Type    | Description                                                                                            |
| ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| channelID<mark style="color:red;">\*</mark>     | string  | The channel ID.                                                                                        |
| phoneNumberID<mark style="color:red;">\*</mark> | string  | The phone number ID to send the message from.                                                          |
| phone<mark style="color:red;">\*</mark>         | string  | The phone number to send the message to.                                                               |
| templateName<mark style="color:red;">\*</mark>  | string  | The message template name.                                                                             |
| languageCode<mark style="color:red;">\*</mark>  | string  | The language code of the template message.                                                             |
| parameters                                      | object  | Parameters for the message template.                                                                   |
| header                                          | array   | Parameters for template header.                                                                        |
| name                                            | string  | Name of the parameter.                                                                                 |
| value                                           | string  | Value of the parameter.                                                                                |
| body                                            | array   | Parameters for template body.                                                                          |
| name                                            | string  | Name of the parameter.                                                                                 |
| value                                           | string  | Value of the parameter.                                                                                |
| footer                                          | array   | Parameters for template footer.                                                                        |
| name                                            | string  | Name of the parameter.                                                                                 |
| value                                           | string  | Value of the parameter.                                                                                |
| buttons                                         | array   | Parameters for template buttons.                                                                       |
| name                                            | string  | Name of the parameter.                                                                                 |
| value                                           | string  | Value of the parameter.                                                                                |
| withCase                                        | boolean | If true, the message will be sent to the recipient's existing open case or a new case will be created. |
| topicID                                         | integer | The topic ID for new case.                                                                             |
| assigneeType                                    | string  | Assignee type for new case. Value: `"chatbot"` or `"agent"`.                                           |

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

```json
HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The message has been added to queue",
    "caseID": "96212160DF",
    "trxID": "7f1007bf-d04b-4e83-9b2e-e193d3833ba1"
  }
}
```

{% endtab %}

{% tab title="400 40002 (ParamValidationFailed): The parameter validation failed.
40002 (HeaderValidationFailed): The request header validation failed.
49900 (TierNotSelected): The organization has not selected the tier." %}

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


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


HTTP/1.1 200 OK
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Click the <mark style="background-color:orange;">**right arrow**</mark> above on the right side of Sync User Contact API to see the full list of request parameters and the response.
{% endhint %}

{% hint style="warning" %}
**Channel ID** can be seen in [OneTalk Dashboard](https://onetalk.taptalk.io)\
Go to **Integration** and click **WhatsApp Business API**, then click the channel detail and you can copy the **Channel ID**&#x20;
{% endhint %}

{% tabs %}
{% tab title="Request Example " %}

```json
{
  "channelID": "2100480937",
  "phoneNumberID": "103011859190563",
  "phone": "6281212345678",
  "templateName": "greetings_v1",
  "languageCode": "en",
  "parameters": {
    "header": [
      //Text Template Type, Header with Variable
      {
        "name": "variable_name",
        "value": "Good Morning"
      },
      //Dynamic Media Template Type, Media Type "Document"
      {
        "name": "document",
        "value": "https://taptalk.io/file_path_url.pdf"
      },
      //Dynamic Media Template Type, Media Type "Image"
      {
        "name": "image",
        "value": "https://taptalk.io/file_path_url.pdf"
      },
      //Dynamic Media Template Type, Media Type "Video"
      {
        "name": "video",
        "value": "https://taptalk.io/file_path_url.pdf"
      },
    ],
    "body": [
      {
        "name": "name",
        "value": "John"
      },
      {
        "name": "office_hours",
        "value": "09:00 - 17:00"
      }
    ],
    "footer": [],
    "buttons": [
      {
        "name": "url_0",
        "value": "1d-1"
      }
    ]
  },
  "withCase": true,
  "topicID": 1,
  "assigneeType": "chatbot"
}

```

{% endtab %}
{% endtabs %}

## Get Updated Case List

<mark style="color:blue;">`GET`</mark> `https://onetalk-api.taptalk.io/api/integration/v1/inbox/case/get_updated_list`

Get the list of new and updated cases since `since_timestamp`.

#### Headers

| Name                                      | Type   | Description                                     |
| ----------------------------------------- | ------ | ----------------------------------------------- |
| API-Key<mark style="color:red;">\*</mark> | string | API key for accessing the API                   |
| Content-Type                              | string | Content type of the request body.               |
| User-Agent                                | string | The user agent of the client accessing the API. |

#### Request Body

<table><thead><tr><th>Name</th><th width="189">Type</th><th>Description</th></tr></thead><tbody><tr><td>since_timestamp	<mark style="color:red;">*</mark></td><td>long</td><td>Timestamp in Unix milliseconds to start getting the updates from.<br></td></tr><tr><td>limit</td><td>integer</td><td><p>Maximum number of items to retrieve.</p><p>Default value: <code>100</code></p><p>Size range: <code>1..100</code></p></td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Response Success" %}

```javascript
HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "cases": [
      {
        "id": "00C49D438C",
        "contact": {
          "id": "76379c2a-14b7-4c88-88c7-17244be50acf",
          "fullName": "Jony XL",
          "alias": "",
          "email": "",
          "phone": "6287776325008",
          "agentRemark": "",
          "createdTime": 1587352926788,
          "updatedTime": 0
        },
        "agent": {
          "email": "jony@taptalk.io",
          "fullName": "Jony"
        },
        "firstMessage": "1",
        "isClosed": false,
        "isJunk": false,
        "agentRemark": "",
        "createdTime": 1587352928385,
        "updatedTime": 1640367746510
      }
    ],
    "hasMore": false,
    "lastTimestamp": 1640367746510
  }
}
```

{% endtab %}

{% tab title="400: Bad Request Error 4xx (ParamValidationFailed, HeaderValidationFailed, TierNotSelected)" %}

```javascript
40002 (ParamValidationFailed): The parameter validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Since timestamp is invalid",
    "field": "since_timestamp"
  },
  "data": {}
}

40002 (HeaderValidationFailed): The request header validation failed.
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

49900 (TierNotSelected): The organization has not selected the tier.
HTTP/1.1 200 OK
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Click the <mark style="background-color:orange;">**right arrow**</mark> above on the right side of Get Updated Case List API to see the full list of request parameters and the response.
{% endhint %}

{% tabs %}
{% tab title="Request Example" %}

```go
?since_timestamp=1640367001000&limit=100

```

{% endtab %}
{% endtabs %}

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

```json
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "cases": [
      {
        "id": "00C49D438C",
        "contact": {
          "id": "76379c2a-14b7-4c88-88c7-17244be50acf",
          "fullName": "John Doe",
          "alias": "",
          "email": "",
          "phone": "628123456789",
          "agentRemark": "",
          "createdTime": 1587352926788,
          "updatedTime": 0
        },
        "agent": {
          "email": "agent@taptalk.io",
          "fullName": "Agent"
        },
        "firstMessage": "1",
        "isClosed": false,
        "isJunk": false,
        "agentRemark": "",
        "createdTime": 1587352928385,
        "updatedTime": 1640367746510
      }
    ],
    "hasMore": false,
    "lastTimestamp": 1640367746510
  }
}
```

{% endtab %}
{% endtabs %}

![Success 200 Field Description](/files/Roa5noVE6GdHXdDkE6PT)

## Update Case

<mark style="color:green;">`POST`</mark> `https://onetalk-api.taptalk.io/api/integration/v1/inbox/case/update`

Update a case details. Only specify parameter for fields to be updated.

#### Headers

| Name                                      | Type   | Description                                     |
| ----------------------------------------- | ------ | ----------------------------------------------- |
| API-Key<mark style="color:red;">\*</mark> | string | API key for accessing the API                   |
| Content-Type                              | string | Content type of the request body.               |
| User-Agent                                | string | The user agent of the client accessing the API. |

#### Request Body

<table><thead><tr><th>Name</th><th width="189">Type</th><th>Description</th></tr></thead><tbody><tr><td>caseID<mark style="color:red;">*</mark></td><td>string</td><td>The case id.</td></tr><tr><td>agentRemark</td><td>string</td><td>Agent's Remark for the case, may be empty.</td></tr><tr><td>isJunk</td><td>boolean</td><td>If the case is junk.</td></tr></tbody></table>

{% tabs %}
{% tab title="Request Example" %}

```json
{
    "caseID": "00C49D438C",
    "agentRemark": "...",
    "isJunk": true
}
```

{% endtab %}
{% endtabs %}

200 Success Response

| Field   | Type    | Description              |
| ------- | ------- | ------------------------ |
| success | boolean | If updated successfully. |
| message | string  | The message.             |

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

```json
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "Case updated successfully",
  }
}
```

{% endtab %}
{% endtabs %}

4xx Error Response

| Name                   | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.                                     |
| FeatureNotAvailable    | The feature is not available due to the organization's current tier. |
| HeaderValidationFailed | The request header validation failed.                                |
| TierNotSelected        | The organization has not selected a tier.                            |

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

```json
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Case ID is required",
    "field": "caseID"
  },
  "data": {}
}
```

{% endtab %}

{% tab title="FeatureNotAvailable" %}

```json
{
  "status": 499,
  "error": {
    "code": "49901",
    "message": "This feature is not available for your current tier",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}

{% tab title="HeaderValidationFailed" %}

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

{% endtab %}

{% tab title="TierNotSelected" %}

```json
{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "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/onetalk-omnichannel-documentation/onetalk-integration-api/inbox-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.