> For the complete documentation index, see [llms.txt](https://polser.gitbook.io/polser-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polser.gitbook.io/polser-docs/api-docs/api-reference/messages.md).
# Messages
{% hint style="info" %}
Text, voice note, sticker, video, file and reply-button messages are free-form messages, so they can only be sent while the user's 24-hour window is open. The window opens when the user writes to you and renews each time they write again. If the window is closed, or the user has never written to you, send a template message instead: templates can be sent at any time. Each request can contain only one message type.
{% endhint %}
## Send a text message
`POST` `/meta/send-message`
Send a text message to a user through your Polser account
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account. ***preview\_url*** is an optional parameter that you can use to disable URL previews in the message sent.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"message": "hey there!",
"source_phone": "+44XXXXXXXXX", // Optional
"preview_url": false // Optional, true by default
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"message": "Message sent"
}
```
The message was sent successfully.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Customer last message date is more than 24 hours"
}
```
The message was not sent because the 24-hour window with this phone number has closed, send a template instead.
```json
{
"error": "Use a template to send a message to this number"
}
```
The message was not sent because you have not contacted this number yet, and Meta doesn't allow you to send text messages to new customers, send a template instead.
```json
{
"error": "Source phone is required for multinumber accounts"
}
```
The message was not sent because you have not provided a ***source\_phone*** in the request but your account has multiple phone numbers activated.
{% endtab %}
{% tab title="401" %}
{
"error": "Unauthorized"
}
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
## Send a voice note
`POST` `/meta/send-message`
Send a voice note to a user through your Polser account
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
***audio\_url*** is a required parameter that must point to a URL that is publicly accessible by Polser. ***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"audio_url": "https://link-to-ogg-file",
"source_phone": "+44XXXXXXXXX", // Optional
}
```
**Response**
{% tabs %}
{% tab title="202" %}
```json
{
"status": "queued",
"job_id": "xxxxx-xxxxx-xxxxx-xxxxx"
}
```
The message was queued to be transcoded in a format that Meta accepts.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "audio_url must be a non-empty string"
}
```
```json
{
"error": "audio_url must be a string"
}
```
The ***audio\_url*** parameter is malformed or can't be accessed.
```json
{
"error": "Failed to send voice note"
}
```
There was an unknown error sending the voice note through Meta.
{% endtab %}
{% tab title="401" %}
{
"error": "Unauthorized"
}
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
## Send a template message
`POST` `/meta/send-message`
Send a template message to a user through your Polser account
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
This method only accepts variables that exist in the `BODY` of the Meta template. ***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account. Additionally, if your template has custom reply buttons, you can attach a custom payload to them. That way, when Polser sends the user reply event to your webhooks, it will include the custom payload.
\
If the template's `HEADER` is an image or video, pass `header_url` pointing to a publicly accessible file — Polser downloads it and attaches it as the template header. Document-header templates aren't supported through this endpoint.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"template_name": "appointment_confirmation",
"variables": [
"John",
"10:00 PM"
],
"source_phone": "+44XXXXXXXXX", // Optional
"header_url": "https://cdn.example.com/promo-image.png", // Optional, required if the template header is IMAGE or VIDEO
// if your template has Custom reply buttons
// you can attach a payload to the replies
// to receive them in the webhook event
"button_payloads": [ // Optional
{ "index": 0, "payload": "custom_payload_for_button_0" },
{ "index": 1, "payload": "custom_payload_for_button_0" }
]
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"message": "Template sent successfully"
}
```
The message was sent successfully.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Template not found, not approved or invalid variables"
}
{
"error": "Template requires an image header. Provide header_url with a publicly accessible image URL."
}
{
"error": "Document header templates are not supported via this API. Use the inbox or omit header_url."
}
{
"error": "Template header expects image but header_url appears to be video (video/mp4)."
}
```
Check that the template name is correct and that it's approved in Meta. Also check that the number of variables that the template requires matches the number of variables you provided.
{% endtab %}
{% tab title="401" %}
{
"error": "Unauthorized"
}
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
## Send a sticker message
`POST` `/meta/send-message`
Send a sticker message to a user through your Polser account
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
***sticker*** is the number of the sticker in your Polser account. You can find this number by hovering over the sticker you want to send:
***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"sticker": 1, // Sticker number
"source_phone": "+44XXXXXXXXX" // Optional
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"message": "Sticker sent successfully"
}
```
The message was sent successfully.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "No stickers configured for this tenant"
}
```
Make sure to have at least one sticker saved in your Polser account.
```json
{
"error": "Sticker not found"
}
```
Make sure to point to the right sticker number that you want to use. Count them starting from 1.
```json
{
"error": "Failed to send sticker"
}
```
There was an unknown error sending the sticker through Meta.
{% endtab %}
{% tab title="401" %}
```json
{
"error": "Unauthorized"
}
```
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
## Send a video
`POST` `/meta/send-message`
Send a free-form video to a user through your Polser account.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
***video\_url*** is a required parameter that must point to a URL that is publicly accessible by Polser. The video must be MP4 or 3GPP and up to 16 MB. ***caption*** is an optional text shown with the video (up to 1,024 characters). ***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"video_url": "https://example.com/welcome.mp4",
"caption": "Welcome to our school!", // Optional
"source_phone": "+44XXXXXXXXX" // Optional
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"message": "Video sent successfully"
}
```
The message was sent successfully.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Customer last message date is more than 24 hours ago"
}
```
The message was not sent because the 24-hour window with this phone number has closed, send a template instead.
```json
{
"error": "Use a template to send a message to this recipient"
}
```
The message was not sent because you have not been contacted by this number yet, send a template instead.
```json
{
"error": "Video must be MP4 or 3GPP (video/mp4 or video/3gpp). Detected content type: video/quicktime."
}
```
```json
{
"error": "Video exceeds Meta's 16 MB limit (20971520 bytes)."
}
```
The video does not meet Meta's requirements. Use an MP4 or 3GPP file of up to 16 MB.
```json
{
"error": "Could not download video_url. Provide a publicly accessible HTTPS link."
}
```
Polser could not download the video from the link you provided.
```json
{
"error": "caption must be at most 1024 characters"
}
```
```json
{
"error": "Failed to send video"
}
```
There was an unknown error sending the video through Meta.
```json
{
"error": "Exactly one of message, template_name, sticker, audio_url, video_url, document_url (or file_url), or interactive_body with buttons must be provided"
}
```
Each request can contain only one message type.
{% endtab %}
{% tab title="401" %}
```json
{
"error": "Unauthorized"
}
```
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
## Send a file
`POST` `/meta/send-message`
Send a free-form file to a user through your Polser account.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
***document\_url*** (you can also use ***file\_url***) is a required parameter that must point to a URL that is publicly accessible by Polser. Supported files are PDF, Word, PowerPoint, Excel and plain text, up to 100 MB. ***filename*** is the optional name the user sees; if you leave it out, Polser takes it from the link. ***caption*** is an optional text shown with the file (up to 1,024 characters). ***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"document_url": "https://example.com/brochure.pdf",
"filename": "Brochure.pdf", // Optional
"caption": "Here is the information you asked for", // Optional
"source_phone": "+44XXXXXXXXX" // Optional
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"message": "Document sent successfully"
}
```
The message was sent successfully.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Customer last message date is more than 24 hours ago"
}
```
The message was not sent because the 24-hour window with this phone number has closed, send a template instead.
```json
{
"error": "Use a template to send a message to this recipient"
}
```
The message was not sent because you have not been contacted by this number yet, send a template instead.
```json
{
"error": "Document type is not supported. Use PDF, Word, PowerPoint, Excel, or plain text. Detected content type: image/png."
}
```
```json
{
"error": "Document exceeds Meta's 100 MB limit (110000000 bytes)."
}
```
The file does not meet Meta's requirements. Use a PDF, Word, PowerPoint, Excel or plain text file of up to 100 MB.
```json
{
"error": "Could not download document_url. Provide a publicly accessible HTTPS link."
}
```
Polser could not download the file from the link you provided.
```json
{
"error": "caption must be at most 1024 characters"
}
```
```json
{
"error": "Failed to send document"
}
```
There was an unknown error sending the file through Meta.
```json
{
"error": "Exactly one of message, template_name, sticker, audio_url, video_url, document_url (or file_url), or interactive_body with buttons must be provided"
}
```
Each request can contain only one message type.
{% endtab %}
{% tab title="401" %}
```json
{
"error": "Unauthorized"
}
```
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
## Send a message with reply buttons
`POST` `/meta/send-message`
Send a free-form message with up to three reply buttons to a user through your Polser account.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `your-api-key` |
**Body**
***interactive\_body*** (the message text, up to 1,024 characters) and ***buttons*** are both required. ***buttons*** takes between 1 and 3 items. Each button has an ***id***, an identifier of your choice (up to 256 characters, unique within the message), and a ***label***, the text the user sees on the button (up to 20 characters). ***source\_phone*** is an optional parameter for those customers who have multiple phone numbers in their Polser account.
```json
{
"phone_number": "+34XXXXXXXXX",
"bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
"interactive_body": "What would you like to do?",
"buttons": [
{ "id": "see_prices", "label": "See prices" },
{ "id": "book_class", "label": "Book a class" },
{ "id": "talk_to_us", "label": "Talk to someone" }
],
"source_phone": "+44XXXXXXXXX" // Optional
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"message": "Interactive message sent successfully"
}
```
The message was sent successfully.
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Customer last message date is more than 24 hours ago"
}
```
The message was not sent because the 24-hour window with this phone number has closed, send a template instead.
```json
{
"error": "Use a template to send a message to this recipient"
}
```
The message was not sent because you have not been contacted by this number yet, send a template instead.
```json
{
"error": "interactive_body and buttons must both be provided together"
}
```
```json
{
"error": "buttons must contain between 1 and 3 items"
}
```
```json
{
"error": "buttons[0].label must be at most 20 characters"
}
```
```json
{
"error": "buttons[0].id must be at most 256 characters"
}
```
```json
{
"error": "button ids must be unique"
}
```
```json
{
"error": "interactive_body must be at most 1024 characters"
}
```
The buttons or the message text do not meet the limits. Check the number of buttons, the length of each label and id, that ids are unique, and the length of the message text.
```json
{
"error": "Failed to send interactive message"
}
```
There was an unknown error sending the message through Meta.
```json
{
"error": "Exactly one of message, template_name, sticker, audio_url, video_url, document_url (or file_url), or interactive_body with buttons must be provided"
}
```
Each request can contain only one message type.
{% endtab %}
{% tab title="401" %}
```json
{
"error": "Unauthorized"
}
```
The API key is missing or incorrect.
{% endtab %}
{% endtabs %}
