Send RCS
POST/api/v1/rcs/send
Send an RCS message to one or more recipients, with optional buttons and an SMS to fall back on for recipients who can't receive RCS. Each request supports up to 1500 recipients.
Before you can send, RCS has to be enabled for your account and the account needs an approved RCS sender. Both are set up by HelloSMS: contact support. List RCS senders shows the senders you can send from.
Formats. You don't choose a format. It follows from what you send, and the response tells you which one was used in rcsFormat:
messagewith up to 160 characters is a plain text message (basic). A longermessageis a text card (single).cardis a card (single) with a title, text, an image and up to 4 buttons, which are itssuggestions. The image goes above the text, or to the left or right of it withimagePlacement.cardsis a carousel (carousel) of 2 to 10 cards that the recipient swipes through. It has nomessage.documentis a PDF (document). It has no text.
Send exactly one of message, card, cards and document; combining them is refused. The top-level suggestions can go with any of them, and so can smsFallback. imageHeight is set once for the whole message, so one height applies to every card in a carousel.
A card needs some content: a title, text, an image or a button. Title and image are both optional. A card with nothing in it is refused. A single card with only text is sent as a text message, the same as if you had sent it as message. In cards, a card with only text is still a card. A card with only buttons is still a card (single). An image to the left or right of the text needs a title, text or buttons, takes no imageHeight, and can't be used in a carousel.
Price. The price follows the format. A basic message is priced as basic. A single, a carousel and a document are all priced as single, and a carousel costs the same whatever the number of cards.
Media. An image on a card, and the PDF of a document, are sent as a media ID instead of in the request. Upload media gives you the ID of an image. Start a PDF upload gives you the ID of a PDF. A media ID works for 24 hours.
Request
- application/json
- Body
- Text only
- Text with a reply and a link button
- Text with an SMS fallback
- Long text
- Card with an image and buttons
- Carousel
- Document
- Test mode
Body
Details of the RCS message to be sent.
- Array [oneOf
- reply
- openUrl
- dial
- viewLocation
- shareLocation
- createCalendarEvent
- ]
- Array [oneOf
- reply
- openUrl
- dial
- viewLocation
- shareLocation
- createCalendarEvent
- ]
- Array [
- Array [oneOf
- reply
- openUrl
- dial
- viewLocation
- shareLocation
- createCalendarEvent
- ]
- ]
The recipients: an array of 1 to 1500 phone numbers, or a single number as a string. Only bare phone numbers are accepted: digits with an optional leading +. Contact lists are not supported.
Possible values: >= 1, <= 1500
The RCS text. Up to 160 characters is sent as plain RCS text (rcsFormat is basic); longer text is sent as a text card with no title or image (single). The format is chosen automatically. The text can be at most 2000 characters, counted as characters and not bytes; a longer text is refused with a 400, also with testMode. Send exactly one of message, card, cards and document.
Possible values: <= 2000 characters
The id of one of your RCS senders, from List RCS senders, for example RCS3F9A0C21. Leave it out to use your default sender.
suggestions object[]
Up to 11 buttons shown under the message. Every button has a type and a caption; the other fields depend on the type.
Possible values: <= 11
A reply the recipient can send with one tap.
Possible values: [reply]
The text on the button.
Possible values: <= 25 characters
The value your integration receives when the recipient taps the reply. Defaults to the caption.
Possible values: <= 2000 characters
card object
A card. It needs at least one of title, text, mediaId and suggestions; a card with none of them is refused. As the single card of a message, a card with only text is sent as a text message; in cards it stays a card. Any other field is refused.
The title of the card. Not blank.
Possible values: <= 200 characters
The text of the card. Not blank.
Possible values: <= 2000 characters
The image of the card, as a media ID from Upload media, for example MED3F9A01BC. A media ID of a PDF is refused. With testMode you can also use a test media ID (it starts with TST); a real send refuses it.
Possible values: Value must match regular expression ^(MED|TST)[0-9A-F]{8}$
suggestions object[]
Up to 4 buttons shown on the card. They are the same as the buttons under the message in suggestions.
Possible values: <= 4
A reply the recipient can send with one tap.
Possible values: [reply]
The text on the button.
Possible values: <= 25 characters
The value your integration receives when the recipient taps the reply. Defaults to the caption.
Possible values: <= 2000 characters
Where the image goes: above the text (the default), or to the left or right of it. It needs mediaId. left and right also need a title, text or suggestions, and can't be used together with imageHeight. It can't be set on a card in cards.
Possible values: [above, left, right]
abovecards object[]
A carousel: 2 to 10 cards that the recipient swipes through (rcsFormat is carousel). Send it instead of message, card and document. For one card, use card. Each card is as described under card, except that it can't set imagePlacement. imageHeight applies to every card.
Possible values: >= 2, <= 10
The title of the card. Not blank.
Possible values: <= 200 characters
The text of the card. Not blank.
Possible values: <= 2000 characters
The image of the card, as a media ID from Upload media, for example MED3F9A01BC. A media ID of a PDF is refused. With testMode you can also use a test media ID (it starts with TST); a real send refuses it.
Possible values: Value must match regular expression ^(MED|TST)[0-9A-F]{8}$
suggestions object[]
Up to 4 buttons shown on the card. They are the same as the buttons under the message in suggestions.
Possible values: <= 4
A reply the recipient can send with one tap.
Possible values: [reply]
The text on the button.
Possible values: <= 25 characters
The value your integration receives when the recipient taps the reply. Defaults to the caption.
Possible values: <= 2000 characters
Where the image goes: above the text (the default), or to the left or right of it. It needs mediaId. left and right also need a title, text or suggestions, and can't be used together with imageHeight. It can't be set on a card in cards.
Possible values: [above, left, right]
abovedocument object
A PDF to send in place of a message. A document has no text, so it can't be sent with message, card or cards, and imageHeight can't be used with it. A smsFallback can be sent with it, but without browserLink.
The media ID of the PDF, from Start a PDF upload and Complete a PDF upload. The PDF can be at most 50 MB. There is no test media ID for a PDF: with testMode you use a real one.
Possible values: Value must match regular expression ^MED[0-9A-F]{8}$
The file name the recipient sees, for example Invoice 1234.pdf. It can't have slashes or hidden characters in it.
Possible values: <= 200 characters
How tall the images are: short, medium (the default) or tall. It is set once and applies to every card in cards. It needs a card, or at least one card in cards, with an image. It can't be used with a document, or with a card whose imagePlacement is left or right.
Possible values: [short, medium, tall]
mediumsmsFallback object
The SMS to send when a recipient can't receive RCS.
Turn the SMS fallback on. When true, text is required.
falseThe text of the SMS.
An optional subject for the SMS, for internal reference within your HelloSMS account.
Add a short "view in browser" link to the SMS. It replaces a [view-in-browser] placeholder in text if there is one; otherwise it is appended.
falsesender object
The sender of the SMS. Leave it out to send from your account's default number.
A custom sender text to show instead of your default phone number.
Possible values: >= 3 characters and <= 11 characters
One of your senders or numbers, by its id from List senders: SND… for a registered sender (for example SND3F9A0C21) or NUM… for one of your numbers (for example NUM5E0C8A17). Use either name or senderId, not both.
Enable link shortening for the SMS text. Defaults to the top-level shortLinks value.
The domain for shortened links in the SMS. Defaults to the top-level shortLinksDomain value.
Possible values: [ff.nu, out.io]
An optional subject for internal reference within your HelloSMS account. If not provided, it defaults to "API".
Send the message later. Give the send time as a UNIX timestamp, for example 1678886400. A time in the past sends immediately.
Run the request without sending or storing anything, and without using credits. The fields are validated as on a real send. The response has no messageIds and reports the route each recipient would take.
Send delivery status callbacks for this message, to callbackUrl or to your account's default callback URL. Off by default. Setting callbackUrl turns it on. The callback says whether the message was delivered as RCS or as SMS, in a channel field. See Delivery callbacks for the format.
The https URL that delivery status callbacks for this message are sent to. See Delivery callbacks for the format.
Possible values: <= 2048 characters
Your own reference, for example an order id. It comes back in the delivery status callbacks, so you can match them to the message.
Possible values: <= 100 characters
Enable link shortening for the RCS text. When set to true, any URLs (starting with http:// or https://) in your message will be automatically shortened using the HelloSMS link shortening service. smsFallback.shortLinks does the same for the SMS and defaults to this value.
When using the link shortening feature, you can select which domain you prefer for the shortened links. HelloSMS offers two options: ff.nu (currently the default) and out.io (note: up until 2025-05-09, out.io was the default).
Possible values: [ff.nu, out.io]
{
"to": [
"46701740610"
],
"message": "Your table at Bistro is booked for Friday at 19:00."
}
{
"to": [
"46701740610"
],
"rcsSenderId": "RCS3F9A0C21",
"message": "Your table at Bistro is booked for Friday at 19:00. Can you make it?",
"suggestions": [
{
"type": "reply",
"caption": "Yes, see you then",
"postback": "booking-4821-confirm"
},
{
"type": "openUrl",
"caption": "View booking",
"url": "https://example.com/bookings/4821"
}
]
}
{
"to": [
"46701740610"
],
"message": "Your table at Bistro is booked for Friday at 19:00.",
"smsFallback": {
"enabled": true,
"text": "Bistro: your table is booked for Friday at 19:00.",
"browserLink": true,
"sender": {
"name": "Bistro"
}
}
}
{
"to": [
"46701740610"
],
"message": "Hi Anna, thanks for booking with Bistro Linnea. Your table for four is reserved for Friday 12 September at 19:00. Please arrive ten minutes early, and tell us about any allergies before then."
}
{
"to": [
"46701740610"
],
"imageHeight": "tall",
"card": {
"title": "Your table is booked",
"text": "Bistro Linnea, Friday at 19:00. Table for four.",
"mediaId": "MED3F9A01BC",
"suggestions": [
{
"type": "reply",
"caption": "Cancel",
"postback": "booking-4821-cancel"
},
{
"type": "openUrl",
"caption": "View booking",
"url": "https://example.com/bookings/4821"
}
]
}
}
{
"to": [
"46701740610"
],
"imageHeight": "short",
"cards": [
{
"title": "Margherita",
"text": "119 kr",
"mediaId": "MED3F9A01BC",
"suggestions": [
{
"type": "reply",
"caption": "Order",
"postback": "order-margherita"
}
]
},
{
"title": "Capricciosa",
"text": "129 kr",
"mediaId": "MED7C21D0E4",
"suggestions": [
{
"type": "reply",
"caption": "Order",
"postback": "order-capricciosa"
}
]
},
{
"title": "See the full menu",
"mediaId": "MED5B80A9F2",
"suggestions": [
{
"type": "openUrl",
"caption": "Open menu",
"url": "https://example.com/menu"
}
]
}
]
}
{
"to": [
"46701740610"
],
"document": {
"mediaId": "MED9D41E6A0",
"fileName": "Invoice 1234.pdf"
}
}
{
"to": [
"46701740610",
"4915112345678"
],
"message": "Your table at Bistro is booked for Friday at 19:00. Can you make it?",
"suggestions": [
{
"type": "reply",
"caption": "Yes, see you then",
"postback": "booking-4821-confirm"
},
{
"type": "openUrl",
"caption": "View booking",
"url": "https://example.com/bookings/4821"
}
],
"smsFallback": {
"enabled": true,
"text": "Bistro: your table is booked for Friday at 19:00.",
"sender": {
"name": "Bistro"
}
},
"testMode": true
}
Responses
- 200
- 400
- 401
- 500
The message was accepted. With testMode, nothing is sent and the response reports the route each recipient would take.
Bad Request.
Unauthorized.
The RCS content could not be stored, so the messages will not be delivered.
rcs-content-persist-failed: the send was queued but its content could not be stored. The messages inmessageIdswill not be delivered.rcs-card-media-store-failed: the image of a card, or the images of a carousel, could not be prepared. Nothing was queued, so there is nomessageIds. Send the request again.rcs-document-store-failed: the document could not be stored. Nothing was queued, so there is nomessageIds. Send the request again.