Skip to main content

​
What are free messages?

Free messages are messages you send without needing an approved template. You can send text, image, audio, video, document — any supported format — with complete freedom of content. The only condition: the conversation window of 24 hours must be open.

​
When can I use them?

The window opens when the customer sends you a message. From that moment, you have 24 hours to send free messages. Each new message from the customer resets the timer.

​
What if the window is closed?

If the customer hasn’t sent a message in the last 24 hours, the window is closed. In this case, the only option is to send a Meta-approved template through the Send template endpoint. After the customer replies to the template, the window reopens and you can use free messages again.
Need to send a template? See how at Send template. To create and manage your templates, go to the Templates section.

​
Available types

All endpoints in this section use the same route: POST /v1/channels/{channelId}/messages What changes is the content.type field:

​
API response

When the send is accepted, the API responds with 200 and the message identifier:
The messageId is a 32-character uppercase hexadecimal string. Store this value: you need it to reply to, react to, or delete the message later.
This is the same value your webhook receives as message._id. Use it to reconcile the send call with the event you receive — see the payload structure.

​
Send errors

When the API refuses the send, the message is not sent. The response carries the HTTP status for the reason and the error code:

​
Disconnected channel

If the channel is not connected at the time of the call, the API responds 422 with code BUSINESS_RULE_VIOLATION and subCode CHANNEL_DISCONNECTED, the body in the example above. The message is not sent and is not kept to go out later. To send again, reconnect the channel (see Connect a channel) and repeat the call.

​
Other errors

Refusals made before the message moves on to sending, such as an invalid Secret Key or an inactive subscription, come in another format, with only the error field.