# Messages API

Channel token is required to access this API resource. Tokens can be generated by using the key icon, next to the desired channel in Settings.

## Requests

The Messages API is composed of several type of requests:

* [Send Text](#sample-post-text-request)
* [Send Attachment](#send-attachment-request)
* [Send Text with Quick Replies](#send-text-with-quick-replies-request)

This request sends a text message directly to the Contact as per defined in the Endpoint.

```
POST /v1/message/sendContent/{contactId}
```

#### Sample POST Text Request

```
curl -X POST \
      https://app.heyx.io/api/v1/message/sendContent/{contactId} \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
  "body": [
  	{
  		"type" : "text",
  		"text" : "Hi there"
  	}
  ]
}'
```

#### Response - **Success (HTTP status → 200)**

```
  {
      "status": "Success",
      "message": "Message Sent",
      "data": []
  }
```

> Please note that in case of Viber Channel - due to a certain limitation - the Contact ID needs to be provided in a **Base64** encoded format.

### Send Attachment Request

This request sends attachment in form of URL directly to the Contact as per defined in the Endpoint. The file can either be image, video, audio or file. 

```
POST /v1/message/sendContent/{contactId}
```

#### Sample POST Send Image Request

```
curl -X POST \
      https://app.heyx.io/api/v1/message/sendContent/{contactId} \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
  "body": [
  	{
  		"type" : "image",
  		"url" : "http://abc.com"
  	}
  ]
}'
```

### &#x20;<a href="#send-attachment-request" id="send-attachment-request"></a>

#### Response - **Success (HTTP status → 200)**

```
  {
      "status": "Success",
      "message": "Message Sent",
      "data": []
  }
```

#### Sample POST Send Video Request

```
curl -X POST \
      https://app.heyx.io/api/v1/message/sendContent/{contactId} \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
  "body": [
  	{
  		"type" : "video",
  		"url" : "http://abc.com"
  	}
  ]
}'
```

#### Response - **Success (HTTP status → 200)**

```
  {
      "status": "Success",
      "message": "Message Sent",
      "data": []
  }
```

#### Sample POST Send Audio Request

```
curl -X POST \
      https://app.heyx.io/api/v1/message/sendContent/{contactId} \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
  "body": [
  	{
  		"type" : "audio",
  		"url" : "http://abc.com"
  	}
  ]
}'
```

#### Response - **Success (HTTP status → 200)**

```
  {
      "status": "Success",
      "message": "Message Sent",
      "data": []
  }
```

#### Sample POST Send File Request

```
curl -X POST \
      https://app.heyx.io/api/v1/message/sendContent/{contactId} \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
  "body": [
  	{
  		"type" : "file",
  		"url" : "http://abc.com"
  	}
  ]
}'
```

#### Response - **Success (HTTP status → 200)**

```
  {
      "status": "Success",
      "message": "Message Sent",
      "data": []
  }
```

### Send Text with Quick Replies Request

This request send text message with quick replies for the receivers.

```
curl -X POST \
      https://app.heyx.io/api/v1/message/sendContent/{contactId} \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
  "body": [
    {
      "type":"quick_reply",
    	"title" : "What is you favorite color?",
    	"replies" : ["Black","Blue","Grey","Red"]
    }
  ]
}'
```

#### Response - **Success (HTTP status → 200)**

```
  {
      "status": "Success",
      "message": "Message Sent",
      "data": []
  }
```

## Error Codes

### **Unauthorized (HTTP Status → 401)**

```
  {
        "status": "error",
        "message": "API Token is invalid.",
        "data": []
  }
```

### **Too Many Requests (HTTP Status → 429)**

```
  {
      "status": "error",
      "message": "Too many requests",
      "data": []
  }
```

### **Method Not Allowed** **(HTTP Status → 405)**

```
  {
      "status": "error",
      "message": "405 Method Not Allowed.",
      "data": []
  }
```

### **General (HTTP Status → 403)**

```
  {
      "status": "error",
      "message": "Message String",
      "data": []
  }
```

### **Unmatched File Type (HTTP Status → 403)**

```
  {
      "status": "error",
      "message": "Sorry, Url provided is not an image/audio/video file",
      "data": []
  }
```

### Limitations

* Only one message can be sent in 1 API call.
* API has rate limit of 25 RPS.
* 10 Quick replies with 20 characters each are allowed.
* Survey is not cancelled by default. `forceCancelSurvey : true` must explicitly be sent in the payload.
* Contact status will not be changed on API call.


---

# 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://heyx.gitbook.io/heyx-integration/welcome/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.