# 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](https://4266585843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LfVupFSqh_qZAY9OiCO%2Fuploads%2FfdzOf86WLGXoZmqs1XLq%2FScreen%20Shot%202022-01-10%20at%2012.23.47.png?alt=media\&token=4718d6b4-0bb5-4cad-9cb8-a24e38c2b2d0)

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