Skip to main content

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:

  • message with up to 160 characters is a plain text message (basic). A longer message is a text card (single).
  • card is a card (single) with a title, text, an image and up to 4 buttons, which are its suggestions. The image goes above the text, or to the left or right of it with imagePlacement.
  • cards is a carousel (carousel) of 2 to 10 cards that the recipient swipes through. It has no message.
  • document is 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​

Body

Details of the RCS message to be sent.

    tostring[]required

    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

    messagestring

    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

    rcsSenderIdstring

    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

  • Array [
  • oneOf
    typestringrequired

    A reply the recipient can send with one tap.

    Possible values: [reply]

    captionstringrequired

    The text on the button.

    Possible values: <= 25 characters

    postbackstring

    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.

    titlestring

    The title of the card. Not blank.

    Possible values: <= 200 characters

    textstring

    The text of the card. Not blank.

    Possible values: <= 2000 characters

    mediaIdstring

    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

  • Array [
  • oneOf
    typestringrequired

    A reply the recipient can send with one tap.

    Possible values: [reply]

    captionstringrequired

    The text on the button.

    Possible values: <= 25 characters

    postbackstring

    The value your integration receives when the recipient taps the reply. Defaults to the caption.

    Possible values: <= 2000 characters

  • ]
  • imagePlacementstring

    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]

    Default value: above
    cards 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

  • Array [
  • titlestring

    The title of the card. Not blank.

    Possible values: <= 200 characters

    textstring

    The text of the card. Not blank.

    Possible values: <= 2000 characters

    mediaIdstring

    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

  • Array [
  • oneOf
    typestringrequired

    A reply the recipient can send with one tap.

    Possible values: [reply]

    captionstringrequired

    The text on the button.

    Possible values: <= 25 characters

    postbackstring

    The value your integration receives when the recipient taps the reply. Defaults to the caption.

    Possible values: <= 2000 characters

  • ]
  • imagePlacementstring

    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]

    Default value: above
  • ]
  • document 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.

    mediaIdstringrequired

    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}$

    fileNamestringrequired

    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

    imageHeightstring

    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]

    Default value: medium
    smsFallback object

    The SMS to send when a recipient can't receive RCS.

    enabledboolean

    Turn the SMS fallback on. When true, text is required.

    Default value: false
    textstring

    The text of the SMS.

    subjectstring

    An optional subject for the SMS, for internal reference within your HelloSMS account.

    browserLinkboolean

    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.

    Default value: false
    sender object

    The sender of the SMS. Leave it out to send from your account's default number.

    namestring

    A custom sender text to show instead of your default phone number.

    Possible values: >= 3 characters and <= 11 characters

    senderIdstring

    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.

    shortLinksboolean

    Enable link shortening for the SMS text. Defaults to the top-level shortLinks value.

    shortLinksDomainstring

    The domain for shortened links in the SMS. Defaults to the top-level shortLinksDomain value.

    Possible values: [ff.nu, out.io]

    subjectstring

    An optional subject for internal reference within your HelloSMS account. If not provided, it defaults to "API".

    delayinteger

    Send the message later. Give the send time as a UNIX timestamp, for example 1678886400. A time in the past sends immediately.

    testModeboolean

    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.

    sendApiCallbackboolean

    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.

    callbackUrlstring<uri>

    The https URL that delivery status callbacks for this message are sent to. See Delivery callbacks for the format.

    Possible values: <= 2048 characters

    callbackRefstring

    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

    shortLinksboolean

    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.

    shortLinksDomainstring

    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]

Responses​

The message was accepted. With testMode, nothing is sent and the response reports the route each recipient would take.