All Products
Search

This Product

    Chat App Message Service:SendChatappMessage

    Document Center

    Chat App Message Service:SendChatappMessage

    Last Updated:Mar 27, 2026

    Sends a message to a specified recipient.

    Operation description

    QPS limits

    This operation allows a maximum of 250 requests per second per account. Excess requests are throttled, which may affect your business. Stay within the specified limit.

    Status changes

    You can monitor the delivery status of messages using Simple Message Queue (SMQ) or HTTP callbacks. For details, see Configure message receipts.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    cams:SendChatappMessage

    create

    *All Resource

    *

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ChannelType

    string

    Yes

    The channel type. Valid values:

    • whatsapp

    • messenger

    • instagram

    • viber

    whatsapp

    Type

    string

    Yes

    The message type. Valid values:

    • template: A message template that has been approved in the console. You can send this type of message at any time.

    • message: A message in any format. You can send this message type only within 24 hours of receiving a user's last message.

    Important

    If Type is set to template, the TemplateCode parameter is required. If Type is set to message, the MessageType parameter is required.

    message

    MessageType

    string

    No

    The specific message type when Type is set to message. Valid values vary by channel:

    WHATSAPP

    • text: A text message.

    • image: An image message.

    • video: A video message.

    • audio: An audio message.

    • document: A document message.

    • interactive: An interactive message.

    • location: A location message.

    • contacts: A contact message.

    • reaction: A reaction message.

    • sticker: A sticker message.

    • typing_indicator: A typing indicator message.

    • pin: A pin message, exclusive to group messages.

    VIBER

    • text: A text message.

    • image: An image message.

    • text_image_button: A message with text, an image, and a button.

    • text_button: A message with text and a button.

    • document: A document message.

    • video: A video message.

    • text_video: A message with text and a video.

    • text_video_button: A message with text, a video, and a button.

    • text_image: A message with text and an image.

    MESSENGER / INSTAGRAM

    • text: A text message.

    • image: An image message.

    • video: A video message.

    • document: A document message.

    • audio: An audio message.

    • interactive: An interactive message.

    • couponTemplate: A coupon template message.

    • regularTemplate: A regular template message.

    • quickReply: A quick reply message.

    • buttonTemplate: A button template message.

    text

    TemplateCode

    string

    No

    The message template code. You can find the template code on the Channel Management > Manage > Template Design page.

    1119***************

    Language

    string

    No

    The message template language. For supported languages and their codes, see Language codes.

    en

    From

    string

    Yes

    The sender's number or ID.

    • If ChannelType is whatsapp, this is the phone number registered with WhatsApp. You can find the number on the Channel Management > Manage > WABA Management > Phone Number Management page.

    • If ChannelType is messenger, this is the Facebook Page ID. You can find the ID on the Channel Management > Manage > Face book Homepage page.

    • If ChannelType is instagram, this is the Instagram Professional Account ID. You can find the ID on the Channel Management > Manage > Professional Account page.

    • If ChannelType is viber, this is the Viber Service ID. You can find the ID on the Channel Management > Manage > Service Number Management page.

    861387777****

    To

    string

    Yes

    The recipient's number or ID.

    • If ChannelType is whatsapp, this is the recipient's phone number.

    • If ChannelType is messenger, this is the Page-Scoped User ID (PSID) generated when a user interacts with your Facebook Page.

    • If ChannelType is instagram, this is the Instagram-Scoped User ID (IGSID) generated when a user interacts with your Instagram business or creator account.

    • If ChannelType is viber, this is the recipient's phone number.

    861388988****

    TemplateParams

    object

    No

    The variables of the message template.

    string

    No

    A template variable, in key-value format.

    { "param1": "value1", "param2": "value2" }

    Content

    string

    No

    The message content, in a JSON-formatted string.

    Notes for WhatsApp messages:

    • If MessageType is text, the text field is required, and the Caption field must not be specified.

    • If MessageType is image, the Link field is required.

    • If MessageType is video, the Link field is required.

    • If MessageType is audio, the Link field is required, and the Caption field is not supported.

    • If MessageType is document, the Link and FileName fields are required, and the Caption field is not supported.

    • If MessageType is interactive, the type and action fields are required.

    • If MessageType is contacts, the name field is required.

    • If MessageType is location, the longitude and latitude fields are required.

    • If MessageType is sticker, the Link field is required. The Caption and FileName fields are not supported.

    • If MessageType is reaction, the messageId and emoji fields are required.

    Notes for Messenger messages:

    • If MessageType is text, the text field is required.

    • If MessageType is image, video, audio, or document, the link field is required.

    Notes for Instagram messages:

    • If MessageType is text, the text field is required.

    • If MessageType is image, video, or audio, the link field is required.

    Notes for Viber messages:

    • If MessageType is text, the text field is required.

    • If MessageType is image, the link field is required.

    • If MessageType is video, the link, thumbnail, fileSize, and duration fields are required.

    • If MessageType is document, the link, fileName, and fileType fields are required.

    • If MessageType is text_button, the text, caption, and action fields are required.

    • If MessageType is text_image_button, the text, link, caption, and action fields are required.

    • If MessageType is text_video, the text, link, thumbnail, fileSize, and duration fields are required.

    • If MessageType is text_video_button, the text, link, thumbnail, fileSize, duration, and caption fields are required. The action field is not supported.

    { "text": "hello,whatsapp", "link": "https://*******", "caption": "****", "fileName": "****" }

    Payload

    array

    No

    An array of payloads triggered when a user clicks a quick reply button.

    payloadtext1,payloadtext2,payloadtext3

    string

    No

    The payload triggered by a quick reply button in the template.

    payloadtext

    CustWabaIddeprecated

    string

    No

    Deprecated. Use CustSpaceId instead. This parameter specifies the WABA ID. For an ISV, this is the customer's WABA ID. For a direct customer, this is the Instance ID. You can find the ID on the Channel Management page.

    cams-8c8*********

    FallBackId

    string

    No

    The fallback strategy ID. This parameter is available only on International Site (alibabacloud.com). You can find the strategy ID on the Fallback Policy page.

    S0****

    FallBackContent

    string

    No

    The custom fallback content. This parameter is available only on International Site (alibabacloud.com).

    Fallback SMS

    IsvCodedeprecated

    string

    No

    Deprecated. The ISV verification code, used to verify if a sub-account is authorized by an ISV. You can ignore this parameter.

    123123******

    CustSpaceId

    string

    No

    The Space ID. For an ISV, this is the sub-customer's Space ID. For a direct customer, this is the Instance ID. You can find the ID on the Channel Management page.

    cams-8c8*********

    ContextMessageId

    string

    No

    The ID of the message to reply to.

    61851ccb2f1365b16aee****

    TrackingData

    string

    No

    The custom tracking data for Viber messages. This parameter is available only on International Site (alibabacloud.com).

    Tracking Data

    Label

    string

    No

    The Viber message type. This parameter is available only on International Site (alibabacloud.com). Valid values:

    • promotion

    • transaction

    promotion

    Ttl

    integer

    No

    The time-to-live (TTL) period, in seconds, for a Viber message. This parameter is available only on International Site (alibabacloud.com). The value must be an integer from 30 to 1209600.

    50

    Tag

    string

    No

    A custom tag for a Viber message.

    tag

    TaskId

    string

    No

    A custom task ID.

    10000****

    FallBackDuration

    integer

    No

    The time to trigger a fallback. This parameter is for the international site (alibabacloud.com). If a delivery receipt is not returned within the specified time, a fallback is triggered. If you leave this parameter empty, the fallback is not determined by time, and is triggered only when the message fails to be sent or a failed status report is received. Unit: seconds. Minimum value: 60. Maximum value: 43200.

    120

    ProductAction

    object

    No

    Product information. This parameter is for WhatsApp channels only. It is the product information that you upload to Meta.

    ThumbnailProductRetailerId

    string

    No

    The ID of the product catalog. Get this ID from the ListProductCatalog API.

    skkks99****

    Sections

    array<object>

    No

    The list of Product Categories. The list can contain a maximum of 10 Categories and 30 Products.

    array<object>

    No

    Product category.

    Title

    string

    No

    The name of the category. View the name on the Channel Management > Manage > Catalog Management > Product Management page or get it from the ListProduct API.

    abcd

    ProductItems

    array<object>

    No

    A list of products.

    object

    No

    Product information.

    ProductRetailerId

    string

    No

    The product ID. View the ID on the Channel Management > Manage > Catalog Management > Product Management page or get it by calling the ListProduct API.

    ksi3****

    FallBackRule

    string

    No

    Fallback rule. This parameter is for the International Site. Valid values:

    • undelivered: The message falls back if it cannot be delivered to the endpoint. This requires that the template and parameters are approved when the message is sent. The system does not check for blocked templates or phone numbers. This is the default rule if the parameter value is empty.

    • sentFailed: The message falls back if parameters, such as the template and template variables, fail validation. Only the channelType, type, messageType, to, and from (existence) parameters are strictly validated.

    undelivered

    FlowAction

    object

    No

    The Flow message object.

    FlowActionData

    object

    No

    The collection of default flow parameters.

    any

    No

    Default flow parameters. The parameters are in key-value format.

    { "name": "name" }

    FlowToken

    string

    No

    The custom flow token.

    kde****

    TemplateName

    string

    No

    The name of the template. Go to the Channel Management> Manage > Template Design page to view the template name.

    test_name

    RecipientType

    string

    No

    The type of recipient. Valid values:

    • individual

    • group

    individual

    MessageCampaignId

    string

    No

    The message campaign ID.

    Note

    This parameter is for testing and is not available.

    123123********

    AdAccountId

    string

    No

    The Meta ad account ID.

    Note

    This parameter is for testing and is not available.

    123123********

    TokenType

    string

    No

    The token type.

    Note

    This parameter is for testing and is not available.

    bearer

    Category

    string

    No

    The message type for WhatsApp direct send.

    UTILITY

    Response elements

    Element

    Type

    Description

    Example

    object

    The response data.

    AccessDeniedDetail

    string

    Details about the access denial.

    None

    RequestId

    string

    The ID of the request.

    90E63D28-E31D-1EB2-8939-A94866******

    Message

    string

    The error message.

    User not authorized to operate on the specified resource.

    Code

    string

    The status code of the request.

    • A value of OK indicates a successful request.

    • For other values, see the Error codes.

    OK

    MessageId

    string

    The ID of the message.

    61851ccb2f1365b16aee****

    Examples

    Success response

    JSON format

    {
  "AccessDeniedDetail": "None",
  "RequestId": "90E63D28-E31D-1EB2-8939-A94866******",
  "Message": "User not authorized to operate on the specified resource.",
  "Code": "OK",
  "MessageId": "61851ccb2f1365b16aee****"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description

    400

    Product.Unsubscript

    You have not subscribed to the specified product.

    You have not subscribed to the specified product.

    400

    Ram.PermissionDeny

    You are not authorized to perform the operation.

    400

    System.LimitControl

    The system is under flow control.

    The system is under flow control.

    400

    Unknown.ResourceOwnerId

    The resource does not belong to the current user.

    The resource does not belong to the current user.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.