Send
POST /:account/messages
A Message can be sent to multiple recipients at the same time by listing each recipient number in the to field.
Examples
Sending a Message
Request
POST /my_account/messages
Body
{
"to": "+13035551234",
"body": "New phone who dis?"
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": "+13035551234",
"body": "New phone who dis?"
}'
Response
Status
201
Response Type
Example Body
{
"@type": "Message",
"id": "/messages/QNDkpL",
"@context": "/contexts/Message.jsonld",
"direction": "out",
"body": "Chuck Norris doesn't use web standards as the web will conform to him.",
"formattedBody": "<div>Chuck Norris doesn't use web standards as the web will conform to him.</div>",
"displayTimestamp": "2018-07-24T20:59:32.156Z",
"timelinePosition": "2018-07-24T20:59:32.156Z",
"deliveryState": "delivered",
"conversation": "/conversations/kY1QwY",
"sender": "/users/hikvlD",
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/joZqVWd/attachments",
"members": [],
"totalItems": 0
},
"friendlyStateDescription": "Message Delivered",
"retryAllowed": false,
"retry": null,
"latestEventAt": "2018-07-24T20:59:32.156Z",
"flags": [],
"source": "textus",
"channel": "sms",
"whatsAppTemplate": null,
"engagementScore": null,
"engagementTemperature": null
}
Sending a Message to multiple Recipients
Request
POST /my_account/messages
Body
{
"to": ["+13035551234", "+13035555678"],
"body": "New phone who dis?"
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": ["+13035551234", "+13035555678"],
"body": "New phone who dis?"
}'
Response
Status
202
Response Type
No body
Sending a Message from a SavedReply
Request
POST /my_account/messages
Body
{
"to": ["+13035551234"],
"body": "New phone who dis?",
"saved_reply": "/saved_replies/QxvonQv"
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": ["+13035551234"],
"body": "New phone who dis?",
"saved_reply": "/saved_replies/QxvonQv"
}'
Response
Status
201
Response Type
No body
Sending a message with attachments
There are limitations to sending an attachment. The attachment has to be under 525KB. You can only send one attachment per request. The media_url must be a public url to the file you want to attach, and you must include the mime type as the value of the content_type property. Current supported file types are as follows: .png, .jpg/.jpeg, .gif, .rtf, .pdf, .ics, and .vcf/.vcard
Request
POST /my_account/messages
Body
{
"to": ["+13035551234"],
"body": "New phone who dis?",
"attachments": [{ "media_url": "https://example.com/example.png", "content_type": "image/png" }]
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": ["+13035551234"],
"body": "New phone who dis?",
"attachments": [{ "media_url": "https://example.com/example.png", "content_type": "image/png" }]
}'
Response
Status
201
Response Type
Example Body
{
"@type": "Message",
"id": "/messages/QNDkpL",
"@context": "/contexts/Message.jsonld",
"direction": "out",
"body": "Chuck Norris doesn't use web standards as the web will conform to him.",
"formattedBody": "<div>Chuck Norris doesn't use web standards as the web will conform to him.</div>",
"displayTimestamp": "2018-07-24T20:59:32.156Z",
"timelinePosition": "2018-07-24T20:59:32.156Z",
"deliveryState": "delivered",
"conversation": "/conversations/kY1QwY",
"sender": "/users/hikvlD",
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/joZqVWd/attachments",
"members": [
{
"@type": "Attachment",
"@context": "/contexts/Attachment.jsonld",
"id": "/attachments/JYngGL",
"url": "https://some_url.com",
"downloadUrl": "https://s3.amazonaws.com/some_url",
"key": "251fea5fce73d0d287e0db77fc2981fe6d01f09a37919ee6e1851c7fd1c2487b.png",
"contentType": "image/png",
"size": 2697,
"width": 300,
"height": 300,
"originalFilename": null
}
],
"totalItems": 1
},
"friendlyStateDescription": "Message Delivered",
"retryAllowed": false,
"retry": null,
"latestEventAt": "2018-07-24T20:59:32.156Z",
"flags": [],
"source": "textus",
"channel": "sms",
"whatsAppTemplate": null,
"engagementScore": null,
"engagementTemperature": null
}
Sending a WhatsApp message with body
WhatsApp messaging must be enabled on the account. To send via WhatsApp, set channel to "whatsapp". An active WhatsApp conversation with the recipient must already exist (i.e. the contact must have sent an inbound WhatsApp message within the last 24 hours).
Request
POST /my_account/messages
Body
{
"to": "+13035551234",
"body": "Thanks for reaching out!",
"channel": "whatsapp"
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": "+13035551234",
"body": "Thanks for reaching out!",
"channel": "whatsapp"
}'
Response
Status
201
Response Type
Example Body
{
"@type": "Message",
"id": "/messages/QNDkpL",
"@context": "/contexts/Message.jsonld",
"direction": "out",
"body": "Chuck Norris doesn't use web standards as the web will conform to him.",
"formattedBody": "<div>Chuck Norris doesn't use web standards as the web will conform to him.</div>",
"displayTimestamp": "2018-07-24T20:59:32.156Z",
"timelinePosition": "2018-07-24T20:59:32.156Z",
"deliveryState": "delivered",
"conversation": "/conversations/kY1QwY",
"sender": "/users/hikvlD",
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/joZqVWd/attachments",
"members": [],
"totalItems": 0
},
"friendlyStateDescription": "Message Delivered",
"retryAllowed": false,
"retry": null,
"latestEventAt": "2018-07-24T20:59:32.156Z",
"flags": [],
"source": "textus",
"channel": "whatsapp",
"whatsAppTemplate": null,
"engagementScore": null,
"engagementTemperature": null
}
Sending a WhatsApp template message
Outside of the 24-hour reply window, you can initiate a conversation using an approved WhatsApp template. Provide a template object with the template’s id and any required variable_values. The body field is not used when sending a template.
Request
POST /my_account/messages
Body
{
"to": "+13035551234",
"channel": "whatsapp",
"template": {
"id": "dkDdrbR",
"variable_values": {
"appt_date": "1/1",
"appt_time": "12:00"
}
}
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": "+13035551234",
"channel": "whatsapp",
"template": {
"id": "dkDdrbR",
"variable_values": {
"appt_date": "1/1",
"appt_time": "12:00"
}
}
}'
Response
Status
201
Response Type
Example Body
{
"@type": "Message",
"id": "/messages/QNDkpL",
"@context": "/contexts/Message.jsonld",
"direction": "out",
"body": "Hi there, please confirm your appointment on 1/1 at 12:00:",
"formattedBody": "<div>Chuck Norris doesn't use web standards as the web will conform to him.</div>",
"displayTimestamp": "2018-07-24T20:59:32.156Z",
"timelinePosition": "2018-07-24T20:59:32.156Z",
"deliveryState": "delivered",
"conversation": "/conversations/kY1QwY",
"sender": "/users/hikvlD",
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/joZqVWd/attachments",
"members": [],
"totalItems": 0
},
"friendlyStateDescription": "Message Delivered",
"retryAllowed": false,
"retry": null,
"latestEventAt": "2018-07-24T20:59:32.156Z",
"flags": [],
"source": "textus",
"channel": "whatsapp",
"whatsAppTemplate": {
"@type": "WhatsApp::Template",
"@context": "/contexts/WhatsApp::Template.jsonld",
"id": "dkDdrbR",
"title": "appointment_reminder",
"language": "en_US",
"status": "approved",
"quality": "high",
"contentSid": "HXabcdef1234567890abcdef1234567890",
"contentType": "quick_reply",
"content": {
"body": "Hi , please confirm your appointment on at :",
"quickReplies": [
{
"id": "confirm",
"title": "Confirm"
},
{
"id": "cancel",
"title": "Cancel"
}
]
},
"category": null,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
},
"engagementScore": null,
"engagementTemperature": null,
"respondedToMessage": null
}
Sending a template that is not approved
Only templates with an approved status can be sent. Attempting to use a pending or rejected template returns a 422.
Request
POST /my_account/messages
Body
{
"to": "+13035551234",
"channel": "whatsapp",
"template": {
"id": "<%= @pending_whats_app_template.to_param %>"
}
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": "+13035551234",
"channel": "whatsapp",
"template": {
"id": "<%= @pending_whats_app_template.to_param %>"
}
}'
Response
Status
422
Response Type
No body
Sending a template with invalid variable values
If the provided variable_values do not satisfy the template’s required variables, the request will be rejected.
Request
POST /my_account/messages
Body
{
"to": "+13035551234",
"channel": "whatsapp",
"template": {
"id": "dkDdrbR",
"variable_values": {
"appt_date": "1/1"
}
}
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": "+13035551234",
"channel": "whatsapp",
"template": {
"id": "dkDdrbR",
"variable_values": {
"appt_date": "1/1"
}
}
}'
Response
Status
422
Response Type
No body
Composing a single message with a custom field
Request
POST /my_account/messages
Body
{
"to": "+13035551234",
"body": "Check out my availability at "
}
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
-H Authorization:"Bearer {token}" \
-X POST /my_account/messages
-d '{
"to": "+13035551234",
"body": "Check out my availability at "
}'
Response
Status
201
Response Type
Example Body
{
"@type": "Message",
"id": "/messages/QNDkpL",
"@context": "/contexts/Message.jsonld",
"direction": "out",
"body": "Check out my availability at https://calend.ly/chuck-norris",
"formattedBody": "<div>Chuck Norris doesn't use web standards as the web will conform to him.</div>",
"displayTimestamp": "2018-07-24T20:59:32.156Z",
"timelinePosition": "2018-07-24T20:59:32.156Z",
"deliveryState": "delivered",
"conversation": "/conversations/kY1QwY",
"sender": "/users/hikvlD",
"attachments": {
"@context": "/contexts/hydra:Collection.jsonld",
"@type": "hydra:Collection",
"id": "/messages/joZqVWd/attachments",
"members": [],
"totalItems": 0
},
"friendlyStateDescription": "Message Delivered",
"retryAllowed": false,
"retry": null,
"latestEventAt": "2018-07-24T20:59:32.156Z",
"flags": [],
"source": "textus",
"channel": "sms",
"whatsAppTemplate": null,
"engagementScore": null,
"engagementTemperature": null
}