Send message

POST https://chatapps.8x8.com/api/v1/subaccounts/:subAccountId/messages

This endpoint is used to send Messaging Apps messages individually (1 request per message). It is ideal to send single personalized messages for use-cases like notifications or alerting for example.

For WhatsApp: When sending a 'text' type message, we will try to match it with registered WhatsApp templates under your account If matching is successful, the message will be submitted as a template to WhatsApp, if not as a normal message

To bypass the template matching and send template only, you can select type 'template' In this case, you need to provide template name, language and parameters

WhatsApp Call Permission Request: You can request permission to call a customer using either:

  • Interactive message: Set type to 'interactive' with interactive.type as 'call_permission_request'. The body field is optional.
  • Template message: Set type to 'template' with your approved Call Permission Request template name and language.

More examples on how this endpoint can be used are available here: Usage examples

Request

Path Parameters

    subAccountId stringrequired

    Possible values: >= 3 characters and <= 50 characters, Value must match regular expression ^[A-Za-z0-9\-._&]{3,50}$

    You must replace {subAccountId} with the subaccountid that you want to use. By default this is generated once you signed up with a new account at https://connect.8x8.com.

Body

Messaging Apps API: request model for send single message

    user objectrequired

    User information

    msisdnstring

    Mobile phone number (MSISDN) to send the message to. International phone number format with '+ sign prefered. In addition we support national (local) phone numbers, please set country field to use it.

    Example: +6500000000
    countrystring

    Default country code (like 'sg', 'uk') for national phone numbers format. You don't need it if msisdn in E.164 format (with '+' sign at the beginning)

    Possible values: <= 2 characters

    Example: SG
    lineUserIdstring

    LINE user ID of the recipient. Use this instead of msisdn when sending messages to a LINE user via the Line Official Account channel.

    Example: Ua12b345678c1de0fg1a1234567891011
    clientMessageIdstring

    Client managed id for the message : your own unique reference

    Possible values: <= 50 characters

    Example: abc-123
    typeContent type (string)required

    Messaging Apps message content type. Allowed values are "text", "image", "audio", "video", "file", "location", "interactive", "template", "carousel" and "richCard".

    • If the type is "text", then content object should contain a "text" parameter.
    • If the type is "image", "audio", "video" or "file", then content object should contain a "url" parameter and all other parameters can be used.
    • If the type is "location", then content object should contain a "latitude", "longitude" parameters.
    • If the type is "interactive", then content object should contain an "interactive" parameter.
    • If the type is "template", then content object should contain a "template" parameter.
    • If the type is "carousel", then content object should contain a "carousel" parameter. Supported for RCS channel only.
    • If the type is "richCard", then content object should contain a "richCard" parameter. Supported for RCS channel only.

    Possible values: [text, audio, video, image, location, file, interactive, template, carousel, richCard]

    Example: Text

    content objectrequired

    Content of the message

    textstring

    Message body - the text of the message

    Possible values: <= 35000 characters

    Example: Hello

    whatsApp object

    WhatsApp-specific message settings. Only applies when the message is delivered via the WhatsApp channel.

    directSend object

    WhatsApp Direct Send settings. When this object is present, the message is sent using the WhatsApp Direct Send API instead of a pre-created template. Direct Send allows you to send business-initiated utility messages without pre-creating a template; matching templates are auto-generated and managed on your behalf.

    Direct Send supports the following message subset:

    • text messages.
    • interactive messages of type cta_url, with a single Call-to-Action URL button defined via interactive.action.parameters.
    • interactive messages of type button (Reply Buttons), with 1–3 buttons.
    • For interactive messages, only text headers are supported.
    categorystringrequired

    Required. Indicates the category of the message to be sent as an auto-generated template. Currently only utility is supported; messages will be charged at utility rates.

    Possible values: [utility]

    Example: utility
    ttlSecondsinteger

    Optional Time-to-live (TTL) in seconds for the message. If the message cannot be delivered within this window, it is dropped. Defaults to 30 days. Minimum 30 seconds, maximum 43200 seconds (12 hours).

    Possible values: >= 30 and <= 43200

    Example: 600
    urlstring<uri>

    Public URL of where the rich content is stored.

    Example: http://example.com
    fallbackTextstring

    In case SMS fallback is triggered, message body - the text of the message

    Possible values: <= 35000 characters

    Example: you can check your account by http://example.com

    sms object

    If the SMS fallback is triggered, here are the SMS settings

    encodingEncoding (string)

    Encoding for the text of the message. "AUTO", "GSM7" and "UCS2"

    Possible values: [AUTO, GSM7, UCS2]

    Example: AUTO
    sourcestring

    Source number (SenderId) - "From" field for SMS. Max length 16 chars.

    Possible values: <= 16 characters

    Example: Info

    location object

    Location object. Required for "location" type

    latitudenumberrequired

    Latitude

    Example: 12.345
    longitudenumberrequired

    Longitude

    Example: 12.345
    namestring

    Text that will appear below the generic map at the top of the message

    Example: Pablo Morales
    addressstring

    Address that will appear below the generic map at the top of the message

    Example: 1 Hacker Way, Menlo Park, CA 94025

    interactive object

    This is an interactive message. Type and Action are required properties

    typestring

    The type of interactive message you want to send.

    Possible values: [button, list, product, product_list, cta_url, flow, call_permission_request, voice_call, location_request_message]

    Example: button

    action object

    Action you want the user to perform after reading the message.

    buttonstring

    Required for List Messages.

    Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not.

    Possible values: <= 20 characters

    buttons object[]

    Required for Reply Buttons.

    Possible values: <= 3

  • Array [
    • typestring

    Type of button

    Possible values: [reply]

    Example: reply

    reply object

    The id and title properties are required.

    idstring

    Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user.

    Possible values: <= 256 characters

    titlestring

    Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not.

    Possible values: <= 20 characters

  • ]
    • catalog_idstring

    Required for Single Product Messages and Multi-Product Messages.

    Unique identifier of the Facebook catalog linked to your WhatsApp Business Account.

    product_retailer_idstring

    Required for Single Product Messages and Multi-Product Messages.

    Unique identifier of the product in a catalog.

    namestring

    Required to be send_location for Location Request Message.

    sections object[]

    Array of section objects.

    Possible values: >= 1, <= 10

  • Array [

    • rows object[]

    Required for List Messages.

    Contains a list of rows. You can have a total of 10 rows across your sections.

    The id and title properties are required.

  • Array [
    • idstring

    Possible values: <= 200 characters

    titlestring

    Possible values: <= 24 characters

    descriptionstring

    Possible values: <= 72 characters

  • ]

    • product_items object[]

    Required for Multi-Product Messages.

    Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.

  • Array [
    • product_retailer_idstring

    Required for Multi-Product Messages. Unique identifier of the product in a catalog. The product_retailer_id property is required.

  • ]
    • titlestring

    Required if the message has more than one section.

    Title of the section.

    Possible values: <= 24 characters

  • ]

    • parameters object

    Required for Call-to-Action Url (cta_url) and voice_call messages.

    display_textstring

    CTA Url button label text. For voice_call, this is the label shown on the call button. Optional; defaults to "Call Now" if omitted. Max 20 characters.

    Possible values: <= 20 characters

    ttlMinutesinteger

    Optional for voice_call only. Overrides the template-level TTL at send time. Must be between 1 min and 43200 mins (30 days). Defaults to 10080 (7 days) if omitted.

    Possible values: >= 1 and <= 43200

    Default value: 10080
    Example: 10
    payloadstring

    Optional for voice_call. Customer-defined payload. Max 512 characters.

    Possible values: <= 512 characters

    urlstring

    URL to load in the device's default web browser when tapped by user.

    flowIdstring

    Required for Flow messages. Unique ID of the Flow provided by WhatsApp.

    Example: 859504979861628
    flowCtastring

    Required for Flow messages. Text on the CTA button. For example: "Signup". CTA text length is advised to be 30 characters or less (no emoji).

    Possible values: <= 30 characters

    Example: Get Recommendations
    flowActionstring

    Optional for Flow messages. Either "navigate" or "data_exchange". Defaults to "navigate" if not provided.

    Possible values: [navigate, data_exchange]

    Default value: navigate
    Example: navigate

    flowActionPayload object

    Optional for Flow messages. Should only be used when flowAction is "navigate". Should be omitted otherwise.

    screenstring

    Optional. The ID of the screen displayed first. It needs to be an entry screen. Defaults to "FIRST_ENTRY_SCREEN" if not provided.

    Default value: FIRST_ENTRY_SCREEN
    Example: RECOMMEND

    data object

    Optional. Input data for the first Screen of the Flow. If provided, this must be a non-empty object. Defaults to null if not provided.

    property name*any

    Optional. Input data for the first Screen of the Flow. If provided, this must be a non-empty object. Defaults to null if not provided.

    Example: {"product_id":"12345","user_name":"John Doe","campaign_id":"summer_sale_2024"}

    header object

    Header content displayed on top of a message. You cannot set a header if your interactive object is of product and location request message type.

    document object

    idstring

    Required when type is audio, document, image, sticker, or video and you are not using a link.

    The media object ID. Do not use this field when message type is set to text.

    linkstring

    Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your server).

    The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.

    captionstring

    Describes the specified image, document, or video media.

    Do not use with audio or sticker media.

    filenamestring

    Describes the filename for the specific document. Use only with document media.

    The extension of the filename will specify what format the document is displayed as in WhatsApp.

    providerstringdeprecated

    This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token.

    image object

    idstring

    Required when type is audio, document, image, sticker, or video and you are not using a link.

    The media object ID. Do not use this field when message type is set to text.

    linkstring

    Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your server).

    The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.

    captionstring

    Describes the specified image, document, or video media.

    Do not use with audio or sticker media.

    filenamestring

    Describes the filename for the specific document. Use only with document media.

    The extension of the filename will specify what format the document is displayed as in WhatsApp.

    providerstringdeprecated

    This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token.

    text object

    idstring

    Required when type is audio, document, image, sticker, or video and you are not using a link.

    The media object ID. Do not use this field when message type is set to text.

    linkstring

    Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your server).

    The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.

    captionstring

    Describes the specified image, document, or video media.

    Do not use with audio or sticker media.

    filenamestring

    Describes the filename for the specific document. Use only with document media.

    The extension of the filename will specify what format the document is displayed as in WhatsApp.

    providerstringdeprecated

    This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token.

    typestring

    The header type you would like to use. The type property is required.

    Possible values: [text, video, image, document]

    Example: text

    video object

    idstring

    Required when type is audio, document, image, sticker, or video and you are not using a link.

    The media object ID. Do not use this field when message type is set to text.

    linkstring

    Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your server).

    The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.

    captionstring

    Describes the specified image, document, or video media.

    Do not use with audio or sticker media.

    filenamestring

    Describes the filename for the specific document. Use only with document media.

    The extension of the filename will specify what format the document is displayed as in WhatsApp.

    providerstringdeprecated

    This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token.

    body object

    Optional for type 'product' and 'call_permission_request'. Required for other message types.

    An object with the body of the message.

    textstring

    The content of the message. Emojis and markdown are supported. The text property is required.

    Possible values: <= 1024 characters

    footer object

    An object with the footer of the message. You cannot set a footer for location request message type

    textstring

    The footer content. Emojis, markdown, and links are supported. The text property is required.

    Possible values: <= 60 characters

    video object

    Video object. Required for "video" type

    thumbnailstring

    ThumbNail

    Example: http://example.com/video.jpg
    filesizenumber

    Video File Size (in bytes)

    Example: 120
    durationnumber

    Duration of video (in seconds)

    Example: 10

    image object

    Image object. Used for Line channel to specify thumbnail for image messages.

    thumbnailstring

    URL of the thumbnail preview image

    Example: https://www.example.com/thumbnail.jpg

    audio object

    Audio object. Used for Line channel to specify duration for audio messages.

    durationnumberrequired

    Duration of audio in seconds

    Example: 300

    template object

    Template data. Mandatory for "template" message type

    namestring

    Template name to use

    Example: auto_reply_message_en_us
    languagestring

    Template language code to use

    Example: en_US

    components object[]

    List of template components

  • Array [
    • typestring

    Component type. Possible values are "header", "footer", "body", "button", "carousel", "call_permission_request"

    Possible values: [header, footer, body, button, carousel, call_permission_request]

    Default value: body

    parameters object[]

    Parameters list to use for template placeholders.

  • Array [
    • typestringrequired

    Parameter type. Possible values are "text", "image", "gif", "video", "document", "location", "payload", "couponCode", "action", "ttlMinutes".

    Use "payload" type to define the payload that will be returned when the button in the interactive message is clicked. Use "action" type for Flow button parameters. Use "ttlMinutes" for VoiceCall button only — overrides the template-level TTL at send time. Using ttlMinutes on any other subtype returns an error.

    Possible values: [text, image, gif, video, document, location, payload, couponCode, action, ttlMinutes]

    textstring

    Text for "text" parameter type

    Example: To be or not to be
    urlstring

    Required for "image", "gif", "video", "document" parameter types.

    Resource URL.
    Note: For type = gif, the url must point to a Video file type, not a .gif.

    Example: http://example.com

    location object

    Required for "location" parameter type.

    Location object.

    latitudenumber

    Latitude

    Example: 12.345
    longitudenumber

    Longitude

    Example: 12.345
    namestring

    Text that will appear below the generic map at the top of the message

    Example: Pablo Morales
    addressstring

    Address that will appear below the generic map at the top of the message

    Example: 1 Hacker Way, Menlo Park, CA 94025
    payloadstring

    Required for "payload" type.

    Customer-defined payload that will be returned when the button in the interactive message is clicked.

    couponCodestring

    Required for "couponCode" type.

    The coupon code to be copied when the customer taps the button.

    flowActionData object

    Optional for "action" type.

    Flow action data for Flow button parameters.

    screenstring

    Optional. The ID of the screen displayed first. It needs to be an entry screen. Should only be used when flow_action is navigate, and should be omitted otherwise. Defaults to "FIRST_ENTRY_SCREEN" if not provided.

    Default value: FIRST_ENTRY_SCREEN
    Example: RECOMMEND

    data object

    Optional. Input data for the first Screen of the Flow. If provided, this must be a non-empty object. Defaults to null if not provided.

    property name*any

    Optional. Input data for the first Screen of the Flow. If provided, this must be a non-empty object. Defaults to null if not provided.

    Example: {"productId":"12345","userName":"John Doe","campaignId":"summer_sale_2024"}
    ttlMinutesinteger

    Required for "ttlMinutes" parameter type (VoiceCall subtype only).

    Overrides the template-level TTL at send time. Must be between 1 min and 43200 mins (30 days). Defaults to 10080 (7 days) if omitted.

    Note: When creating a template, the minimum is 1440 (1 day). When sending, the minimum is 1 (1 minute).

    Possible values: >= 1 and <= 43200

    Default value: 10080
    Example: 2
  • ]
    • indexinteger

    Required for "button" type.

    Position index of the button You can use index values from 0 to 9 to create up to 10 buttons. However, the Url button type allows a maximum of 2 buttons

    Possible values: >= 0 and <= 9

    Default value: 0
    subTypestring

    Required for "button" type.

    Type of button being created Values: QuickReply, Url, CopyCode, Flow, VoiceCall.

    For VoiceCall, the parameters array is optional. All other subtypes require at least one parameter.

    Possible values: [QuickReply, Url, CopyCode, Flow, VoiceCall]

    cards object[]

    Required for "carousel" type.

  • Array [
    • cardIndexinteger

    Index of the card in the carousel.

    Possible values: >= 0 and <= 9

    components object[]

    List of card components

  • Array [
    • typestring

    Component type. Possible values are "header", "body", "button"

    Possible values: [header, body, button]

    Default value: body

    parameters object[]

    Parameters list to use for template placeholders.

  • Array [
    • typestringrequired

    Parameter type. Possible values are "text", "image", "video", "document", "location", "payload", "couponCode".

    Use "payload" type to define the payload that will be returned when the button in the interactive message is clicked.

    Possible values: [text, image, video, document, location, payload, couponCode]

    textstring

    Text for "text" parameter type

    Example: To be or not to be
    urlstring

    Required for "image", "video", "document" parameter types.

    Resource URL.

    Example: http://example.com

    location object

    Required for "location" parameter type.

    Location object.

    latitudenumber

    Latitude

    Example: 12.345
    longitudenumber

    Longitude

    Example: 12.345
    namestring

    Text that will appear below the generic map at the top of the message

    Example: Pablo Morales
    addressstring

    Address that will appear below the generic map at the top of the message

    Example: 1 Hacker Way, Menlo Park, CA 94025
    payloadstring

    Required for "payload" type.

    Customer-defined payload that will be returned when the button in the interactive message is clicked.

    couponCodestring

    Required for "couponCode" type.

    The coupon code to be copied when the customer taps the button.

  • ]
    • indexinteger

    Required for "button" type.

    Position index of the button You can use index values from 0 to 1 to populate up to 2 buttons.

    Possible values: >= 0 and <= 1

    Default value: 0
    subTypestring

    Required for "button" type.

    Type of button being created Values: QuickReply, Url.

    Possible values: [QuickReply, Url]

  • ]
  • ]
  • ]

    • richCard object

    RCS Rich Card message content. Required when type is "richCard". Supported for RCS channel only.

    cardOrientationstringrequired

    Orientation of the card.

    Possible values: [horizontal, vertical]

    Example: vertical
    thumbnailImageAlignmentstring

    Alignment of the thumbnail image. Applicable for horizontal cards.

    Possible values: [left, right]

    Example: right
    titlestring

    Title of the rich card.

    Possible values: <= 200 characters

    descriptionstring

    Description of the rich card.

    Possible values: <= 2000 characters

    media objectrequired

    Media content of the card.

    heightstring

    Height of the media within the card.

    Possible values: [short, medium, tall]

    Example: short

    contentInfo objectrequired

    Information about the media file.

    fileUrlstring<uri>required

    Publicly accessible URL of the media file.

    thumbnailUrlstring<uri>

    Publicly accessible URL of the thumbnail for the media.

    forceRefreshboolean

    If set to true, the RCS platform will fetch the file again even if it has been cached.

    Default value: false

    suggestions object[]

    List of suggested actions or replies for the rich card.

    Possible values: <= 4

  • Array [

    • reply object

    Suggest a reply to the message

    textstringrequired

    Text content of the reply

    Possible values: <= 25 characters

    postbackDatastringrequired

    The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

    Possible values: <= 2048 characters

    action object

    Suggest an action to the message. Only one of the following properties can be specified: dialAction, viewLocationAction, createCalendarEventAction, openUrlAction.

    textstringrequired

    Text content of the reply

    Possible values: <= 25 characters

    postbackDatastringrequired

    The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

    Possible values: <= 2048 characters

    fallbackUrlstring

    URL that will open in a new window if a mobile device doesn't support a suggested action.

    dialAction object

    Opens the device's default phone app with the specified phone number filled in.

    phoneNumberstringrequired

    Phone number to dial, in E.164 format.

    viewLocationAction object

    Opens the device's default map app and selects the specified location or searches around the device's location given an agent-specified query.

    latLong object

    The latitude and longitude of the specified location.

    latitudenumberrequired

    The latitude in degrees.

    Possible values: >= -90 and <= 90

    longitudenumberrequired

    The longitude in degrees.

    Possible values: >= -180 and <= 180

    labelstring

    Text label of the location opened.

    Possible values: <= 100 characters

    querystring

    (Optional, only supported on Android Messages clients) Rather than specify a latLong (and optionally, a label), the agent can instead specify a query string. For default map apps that support search functionality (including Google Maps), tapping this suggested action results in a location search centered around the user's current location. If the query is sufficiently specific, then agents can use it to select any location in the world.

    Possible values: <= 200 characters

    createCalendarEventAction object

    Opens the device's default calendar app and creates a new calendar event prefilled with the event data.

    titlestringrequired

    Event title.

    Possible values: <= 100 characters

    descriptionstring

    Event description.

    Possible values: <= 500 characters

    startTimestringrequired

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

    endTimestringrequired

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

    openUrlAction object

    Opens the specified URL.

    urlstringrequired

    URL. Must be a valid URI as defined in RFC 3986.

    Possible values: <= 2048 characters

    applicationstring

    URL open application, browser or webview. To check whether a user's device supports webview mode, run a capability check first. See the documentation for details: https://developers.google.com/business-communications/rcs-business-messaging/guides/build/capabilities.

    Possible values: [OPEN_URL_APPLICATION_UNSPECIFIED, BROWSER, WEBVIEW]

    Default value: OPEN_URL_APPLICATION_UNSPECIFIED
    webviewViewModestring

    View mode for webview

    Possible values: [OPEN_URL_WEBVIEW_VIEW_MODE_UNSPECIFIED, FULL, HALF, TALL]

    Default value: FULL
    descriptionstring

    Accessibility description for webview.

    Possible values: <= 2048 characters

  • ]

    • carousel object

    RCS Carousel message content. Required when type is "carousel". Supported for RCS channel only.

    cardWidthstringrequired

    The width of the cards in the carousel.

    Possible values: [small, medium]

    Example: medium

    cards object[]required

    List of rich card items in the carousel. Minimum 2 cards, maximum 10 cards.

    Possible values: >= 2, <= 10

  • Array [
    • titlestring

    Title of the card.

    Possible values: <= 200 characters

    descriptionstring

    Description of the card.

    Possible values: <= 2000 characters

    media objectrequired

    Media content of the card.

    heightstring

    Height of the media within the card.

    Possible values: [short, medium, tall]

    Example: short

    contentInfo objectrequired

    Information about the media file.

    fileUrlstring<uri>required

    Publicly accessible URL of the media file.

    thumbnailUrlstring<uri>

    Publicly accessible URL of the thumbnail for the media.

    forceRefreshboolean

    If set to true, the RCS platform will fetch the file again even if it has been cached.

    Default value: false

    suggestions object[]

    List of suggested actions or replies for the card.

    Possible values: <= 4

  • Array [

    • reply object

    Suggest a reply to the message

    textstringrequired

    Text content of the reply

    Possible values: <= 25 characters

    postbackDatastringrequired

    The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

    Possible values: <= 2048 characters

    action object

    Suggest an action to the message. Only one of the following properties can be specified: dialAction, viewLocationAction, createCalendarEventAction, openUrlAction.

    textstringrequired

    Text content of the reply

    Possible values: <= 25 characters

    postbackDatastringrequired

    The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

    Possible values: <= 2048 characters

    fallbackUrlstring

    URL that will open in a new window if a mobile device doesn't support a suggested action.

    dialAction object

    Opens the device's default phone app with the specified phone number filled in.

    phoneNumberstringrequired

    Phone number to dial, in E.164 format.

    viewLocationAction object

    Opens the device's default map app and selects the specified location or searches around the device's location given an agent-specified query.

    latLong object

    The latitude and longitude of the specified location.

    latitudenumberrequired

    The latitude in degrees.

    Possible values: >= -90 and <= 90

    longitudenumberrequired

    The longitude in degrees.

    Possible values: >= -180 and <= 180

    labelstring

    Text label of the location opened.

    Possible values: <= 100 characters

    querystring

    (Optional, only supported on Android Messages clients) Rather than specify a latLong (and optionally, a label), the agent can instead specify a query string. For default map apps that support search functionality (including Google Maps), tapping this suggested action results in a location search centered around the user's current location. If the query is sufficiently specific, then agents can use it to select any location in the world.

    Possible values: <= 200 characters

    createCalendarEventAction object

    Opens the device's default calendar app and creates a new calendar event prefilled with the event data.

    titlestringrequired

    Event title.

    Possible values: <= 100 characters

    descriptionstring

    Event description.

    Possible values: <= 500 characters

    startTimestringrequired

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

    endTimestringrequired

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

    openUrlAction object

    Opens the specified URL.

    urlstringrequired

    URL. Must be a valid URI as defined in RFC 3986.

    Possible values: <= 2048 characters

    applicationstring

    URL open application, browser or webview. To check whether a user's device supports webview mode, run a capability check first. See the documentation for details: https://developers.google.com/business-communications/rcs-business-messaging/guides/build/capabilities.

    Possible values: [OPEN_URL_APPLICATION_UNSPECIFIED, BROWSER, WEBVIEW]

    Default value: OPEN_URL_APPLICATION_UNSPECIFIED
    webviewViewModestring

    View mode for webview

    Possible values: [OPEN_URL_WEBVIEW_VIEW_MODE_UNSPECIFIED, FULL, HALF, TALL]

    Default value: FULL
    descriptionstring

    Accessibility description for webview.

    Possible values: <= 2048 characters

  • ]
  • ]

    • suggestions object[]

    List of suggestioned actions that can be taken by the user for the message

    Possible values: <= 10

  • Array [

    • reply object

    Suggest a reply to the message

    textstringrequired

    Text content of the reply

    Possible values: <= 25 characters

    postbackDatastringrequired

    The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

    Possible values: <= 2048 characters

    action object

    Suggest an action to the message. Only one of the following properties can be specified: dialAction, viewLocationAction, createCalendarEventAction, openUrlAction.

    textstringrequired

    Text content of the reply

    Possible values: <= 25 characters

    postbackDatastringrequired

    The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

    Possible values: <= 2048 characters

    fallbackUrlstring

    URL that will open in a new window if a mobile device doesn't support a suggested action.

    dialAction object

    Opens the device's default phone app with the specified phone number filled in.

    phoneNumberstringrequired

    Phone number to dial, in E.164 format.

    viewLocationAction object

    Opens the device's default map app and selects the specified location or searches around the device's location given an agent-specified query.

    latLong object

    The latitude and longitude of the specified location.

    latitudenumberrequired

    The latitude in degrees.

    Possible values: >= -90 and <= 90

    longitudenumberrequired

    The longitude in degrees.

    Possible values: >= -180 and <= 180

    labelstring

    Text label of the location opened.

    Possible values: <= 100 characters

    querystring

    (Optional, only supported on Android Messages clients) Rather than specify a latLong (and optionally, a label), the agent can instead specify a query string. For default map apps that support search functionality (including Google Maps), tapping this suggested action results in a location search centered around the user's current location. If the query is sufficiently specific, then agents can use it to select any location in the world.

    Possible values: <= 200 characters

    createCalendarEventAction object

    Opens the device's default calendar app and creates a new calendar event prefilled with the event data.

    titlestringrequired

    Event title.

    Possible values: <= 100 characters

    descriptionstring

    Event description.

    Possible values: <= 500 characters

    startTimestringrequired

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

    endTimestringrequired

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

    openUrlAction object

    Opens the specified URL.

    urlstringrequired

    URL. Must be a valid URI as defined in RFC 3986.

    Possible values: <= 2048 characters

    applicationstring

    URL open application, browser or webview. To check whether a user's device supports webview mode, run a capability check first. See the documentation for details: https://developers.google.com/business-communications/rcs-business-messaging/guides/build/capabilities.

    Possible values: [OPEN_URL_APPLICATION_UNSPECIFIED, BROWSER, WEBVIEW]

    Default value: OPEN_URL_APPLICATION_UNSPECIFIED
    webviewViewModestring

    View mode for webview

    Possible values: [OPEN_URL_WEBVIEW_VIEW_MODE_UNSPECIFIED, FULL, HALF, TALL]

    Default value: FULL
    descriptionstring

    Accessibility description for webview.

    Possible values: <= 2048 characters

  • ]
    • scheduledstring<date-time>

    Date and time when a schedule delivery of the message must happen

    expirystring<date-time>

    Message Expiry date-time object. If message is not delivered before specified time, it should be trashed

    dlrCallbackUrlstring<uri>

    Override default DR callback URL for the message

    channels object[]

    Channel fallback override

  • Array [
    • channelChannel type (string)required

    Messaging Apps Channel enumeration

    Possible values: [SMS, WhatsApp, Facebook, RCS, Viber, Line, WeChat, Zalo, Instagram]

    Example: WhatsApp
    fallbackAfterinteger

    Specify the amount of time in seconds, after which message should be sent to next fallback channel, if not delivered to current one. Maximum: 1 day

    Possible values: >= 10 and <= 86400

    successStatusSuccess status (string)

    Enumeration of Success Delivery status

    Possible values: [Accepted, Sent, Delivered, Read]

    Example: Delivered
  • ]

    • context object

    Contextual replies object. This allows you to reply to a specific message in a conversation thread. You can reply to messages up to 7 days old. Only supported for WhatsApp messages.

    For more information and limitations, see WhatsApp Contextual Replies documentation.

    umidstringrequired

    The unique message ID (umid) of the message you want to reply to. This can be the umid from an inbound message (received from the recipient) or an outbound message (previously sent by you). This creates a quoted reply in WhatsApp, showing the original message above your response.

    Example: aa7c29ad-4433-2211-9c8b-00004e2b9ecc

Success response

Schema

    status objectrequired

    Delivery status of the message. Status contains the following information.

    statestring

    General status of the message. Possible values are

    • unknown: Status is not known. This is an exceptional/intermediate status.
    • queued: The request is accepted and queued for processing
    • failed: The request has been rejected by the api and will not be processed.
    • sent: The message has been sent to the operator and we have not received an acknowledgment yet.
    • delivered: Message has been delivered to destination and we have received confirmation from the operator.
    • undelivered: We have received a delivery receipt from the operator that the message was not delivered.
    • read: Message was delivered and read.
    • ok: Operation was successful
    • error: An error occurred during operation
    Example: delivered
    detailstring
    • delivered_to_operator: The message has been delivered to the operator. Associated with delivered state
    • delivered_to_recipient: The message has been delivered to the recipient. Associated with delivered state.
    • rejected_by_operator: The message has been rejected by the operator. Associated with undelivered status.
    • undelivered_to_recipient: The message has been delivered but rejected by the target device. Associated with undelivered state.
    Example: delivered_to_carrier
    errorCodeinteger

    Error code for the operation

    errorMessagestring

    Description of the error.

    Example: Invalid message length
    timestampstring<date-time>

    Date and time when the status was observed expressed in ISO 8601 format.

    Example: 2020-06-17T04:17:21.06Z
    umidstring<uuid>required

    Unique message id (guid) generated by 8x8 CPaaS platform upon message submission

    user objectrequired

    User information

    msisdnstring

    Mobile phone number (MSISDN) to send the message to. International phone number format with '+ sign prefered. In addition we support national (local) phone numbers, please set country field to use it.

    Example: +6500000000
    countrystring

    Default country code (like 'sg', 'uk') for national phone numbers format. You don't need it if msisdn in E.164 format (with '+' sign at the beginning)

    Possible values: <= 2 characters

    Example: SG
    clientMessageIdstring

    Client managed id for the message: your own unique reference

{
"status":{
"state":"delivered",
"detail":"delivered_to_carrier",
"errorCode":0,
"errorMessage":"Invalid message length",
"timestamp":"2020-06-17T04:17:21.06Z"
},
"umid":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"user":{
"msisdn":"+6500000000",
"country":"SG"
},
"clientMessageId":"string"
}
{
"umid":"82188ee0-109f-e811-8150-020897df5459",
"user":{
"msisdn":"+6512341234"
},
"clientMessageId":"1234_id",
"status":{
"state":"queued",
"timestamp":"2021-01-04T08:19:45.99Z"
}
}

Bad request error response

Schema

    codeintegerrequired

    Error code

    messagestring

    Error description

    errorIdstring<uuid>required

    Unique id of error. You can use it as reference when sending enquiries to 8x8 support

    timestampstring<date-time>required

    Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}
{
"code":1002,
"message":"Invalid MSISDN format (not E.164 international number)",
"errorId":"b4478860-b76c-e811-814e-022a35cc1c71",
"timestamp":"2018-08-04T09:25:40.9235752+00:00"
}

Request was not authenticated response

Schema

    codeintegerrequired

    Error code

    messagestring

    Error description

    errorIdstring<uuid>required

    Unique id of error. You can use it as reference when sending enquiries to 8x8 support

    timestampstring<date-time>required

    Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}
{
"code":1200,
"message":"Request was not authenticated properly",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2018-08-02T09:42:38.8988997+00:00"
}

Internal server error

Schema

    codeintegerrequired

    Error code

    messagestring

    Error description

    errorIdstring<uuid>required

    Unique id of error. You can use it as reference when sending enquiries to 8x8 support

    timestampstring<date-time>required

    Data and time of the error occurence

{
"code":1001,
"message":"Provided subAccountId doesn't belongs to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2017-04-19T02:31:19.4297387+00:00"
}
{
"code":2000,
"message":"Internal server error",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2018-07-02T09:42:38.8988997+00:00"
}

Source: https://developer.8x8.com/connect/reference/send-message · 8x8 CPaaS Developer Docs. Synced for support deflection.

Was this article helpful?
or
0 out of 0 found this helpful
Avatar
Stephen - 8x8 Technical Support Level 2

0 Comments

Please sign in to leave a comment.

Didn't find what you were looking for?

Submit a request