All Products
Search

This Product

    Chat App Message Service:CreateChatappTemplate

    Document Center

    Chat App Message Service:CreateChatappTemplate

    Last Updated:Dec 23, 2025

    Creates a message template. After the template is approved, you can use it to send messages.

    Operation description

    QPS limit

    This API is limited to 50 queries per second (QPS) for each user. If you exceed this limit, API calls are throttled, which can affect your business. Call this API within the specified limit.

    Status changes

    You can monitor changes in the status and quality of a template through Simple Message Queue (formerly MNS) or HTTP. For more information, see 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:CreateChatappTemplate

    create

    *All Resource

    *

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    Category

    string

    Yes

    The category of the WhatsApp template:

    • UTILITY: Transactional.

    • MARKETING: Marketing.

    • AUTHENTICATION: Authentication.

    The category of the Viber template:

    • text: Plain text

    • image: Image only

    • text_image_button: Text, image, and button

    • text_button: Text and button

    • document: File

    • video: Video

    • text_video: Text and video

    • text_video_button: Text, video, and button

    • text_image: Text and image

    UTILITY

    Components

    array<object>

    Yes

    A list of template components.

    Note

    If Category is set to AUTHENTICATION, the Components array cannot contain a HEADER component. If the component Type is BODY or FOOTER, the Text parameter must be empty.

    array<object>

    No

    The list of components.

    Type

    string

    Yes

    The component type. Valid values:

    • BODY

    • HEADER

    • FOOTER

    • BUTTONS

    • CAROUSEL

    • LIMITED_TIME_OFFER

    Note

    • For WhatsApp templates, the BODY component cannot exceed 1,024 characters. The HEADER and FOOTER components cannot exceed 60 characters.

    • For Viber templates, the FOOTER, CAROUSEL, and LIMITED_TIME_OFFER types are invalid.

    • For Viber templates, images, videos, and files are placed in the HEADER. The client displays the image below the text.

    BODY

    Text

    string

    No

    The text of the message.

    Note

    If Category is set to AUTHENTICATION, this parameter must be empty.

    hello whatsapp

    Format

    string

    No

    The type of the media resource.

    • TEXT

    • IMAGE

    • DOCUMENT

    • VIDEO

    TEXT

    Url

    string

    No

    The path of the media resource.

    Note

    For Viber templates, the recommended image size is 800 × 800 pixels.

    https://image.developer.aliyundoc.com

    Caption

    string

    No

    The description of the file.

    This is a video

    FileName

    string

    No

    The name of the file.

    Delivery video

    Buttons

    array<object>

    No

    A list of buttons. This parameter applies only to the BUTTONS component.

    Note

    Number of buttons for WhatsApp templates

    • For MARKETING or UTILITY templates, a maximum of 10 buttons are allowed.

    • Only one PHONE_NUMBER button is allowed.

    • A maximum of two URL buttons are allowed.

    • QUICK_REPLY buttons cannot be mixed with PHONE_NUMBER or URL buttons.

    array<object>

    No

    The button definition.

    Type

    string

    Yes

    The button type.

    • PHONE_NUMBER: Call button

    • URL: URL button

    • QUICK_REPLY: Quick reply button

    • COPY_CODE: Copy code button for verification codes or coupon codes.

    • ONE_TAP: Autofill button for AUTHENTICATION templates.

    • ZERO_TAP: Autofill button for AUTHENTICATION templates.

    • MPM: Multi-product message.

    • CATALOG: Catalog.

    • FLOW: Open a WhatsApp flow.

    Note

    • For WhatsApp templates where Category is AUTHENTICATION, only one button is allowed, and its type must be COPY_CODE or ONE_TAP. If the type is COPY_CODE, Text is required. If the type is ONE_TAP, Text (the name of the copy code button that is displayed if the target application is not installed on the client), SignatureHash, PackageName, and AutofillText are required.

    • For Viber templates, only one button is allowed, and its type must be URL.

    PHONE_NUMBER

    Text

    string

    No

    The text displayed on the button.

    Call Me

    PhoneNumber

    string

    No

    The phone number. This parameter is valid only when the button Type is PHONE_NUMBER.

    +861368897****

    Url

    string

    No

    The URL that is accessed when the URL button is clicked.

    https://example.com

    UrlType

    string

    No

    The type of the URL.

    • static

    • dynamic

    static

    SignatureHashdeprecated

    string

    No

    Use the parameters under SupportedApps instead.

    wi299382

    PackageNamedeprecated

    string

    No

    Use the parameters under SupportedApps instead.

    com.demo

    AutofillText

    string

    No

    The button text for the WhatsApp autofill action. This parameter is required for WhatsApp templates when Category is AUTHENTICATION and the button Type is ONE_TAP or ZERO_TAP.

    Autofill

    IsOptOut

    boolean

    No

    This parameter is valid for WhatsApp templates when Category is Marketing and the button Type is QUICK_REPLY. It indicates that the button is a marketing opt-out button. If a customer clicks this button and you have configured sending control in ChatApp, subsequent marketing messages are not sent to the customer.

    false

    CouponCode

    string

    No

    The value of the coupon code. It can contain only letters and digits. You can pass a variable such as $(couponCode) and then provide the actual coupon code when sending the message.

    120293

    FlowId

    string

    No

    The flow ID.

    479884093605****

    FlowAction

    string

    No

    The type of the flow data event. Valid values:

    • DATA_EXCHANGE: Data exchange.

    • NAVIGATE: Navigation.

    NAVIGATE

    NavigateScreen

    string

    No

    The screen to navigate to. This parameter is required when FlowAction is set to NAVIGATE.

    DETAILS

    SupportedApps

    array<object>

    No

    A list of supported applications.

    object

    No

    SignatureHash

    string

    No

    The signature hash of the application that WhatsApp launches. This parameter is required for WhatsApp templates when Category is AUTHENTICATION and the button Type is ONE_TAP or ZERO_TAP.

    ieid83kdiek

    PackageName

    string

    No

    The package name of the application that WhatsApp launches. This parameter is required for WhatsApp templates when Category is AUTHENTICATION and the button Type is ONE_TAP or ZERO_TAP.

    com.kuaidian.waimaistaff

    ThumbUrl

    string

    No

    The thumbnail of a Viber message that contains a video.

    https://cdn.multiplymall.mobiapp.cloud/yunmall/B-LM-LMALL202207130001/20220730/d712a057-a6af-4513-bbe6-7ee57ea60983.png?x-oss-process=image/resize,w_100

    Duration

    integer

    No

    The duration of the video in a Viber video message, in seconds. The value can range from 0 to 600.

    120

    FileType

    string

    No

    The file type of a Viber file message.

    docx

    CodeExpirationMinutes

    integer

    No

    The validity period of the verification code in a WhatsApp AUTHENTICATION template, in minutes. This parameter is valid only for WhatsApp messages when Category is AUTHENTICATION and the component Type is Footer. The information is displayed in the footer.

    5

    AddSecretRecommendation

    boolean

    No

    This parameter is valid for WhatsApp templates when Category is AUTHENTICATION and the component Type is Body. It indicates that a message is displayed above the body, reminding users not to share their verification code with others.

    true

    HasExpiration

    boolean

    No

    Specifies whether the coupon code has an expiration time. This parameter is used when type is LIMITED_TIME_OFFER.

    true

    Cards

    array<object>

    No

    A list of cards for the Carousel template.

    array<object>

    No

    The card object for the Carousel template.

    CardComponents

    array<object>

    Yes

    A list of components in the Carousel card.

    array<object>

    No

    The card object in the Carousel template.

    Type

    string

    Yes

    The component type. Valid values:

    • BODY

    • HEADER

    • BUTTONS

    BODY

    Format

    string

    No

    The type of the media resource. This parameter is valid when Type is HEADER.

    • IMAGE

    • VIDEO

    IMAGE

    Text

    string

    No

    The content of the BODY in the Carousel card.

    Who is the very powerful team

    Url

    string

    No

    The path of the media resource.

    https://alibaba.com/img.png

    Buttons

    array<object>

    No

    A list of buttons. This parameter applies only to the BUTTONS component. Each card in a Carousel template can have a maximum of two buttons.

    object

    No

    The button object.

    Text

    string

    No

    The button text.

    Call me

    Type

    string

    Yes

    The button type.

    • PHONE_NUMBER: Call button

    • URL: URL button

    • QUICK_REPLY: Quick reply button

    PHONE_NUMBER

    Url

    string

    No

    The URL that is accessed when the button is clicked.

    https://alibaba.com/xx

    UrlType

    string

    No

    The URL type.

    • static

    • dynamic

    static

    PhoneNumber

    string

    No

    The phone number.

    +86138007****

    Name

    string

    Yes

    The template name.

    hello_whatsapp

    Language

    string

    Yes

    The template language. For language codes, see Language codes.

    en

    Example

    object

    No

    An example of the template.

    hello_whatsapp

    string

    No

    An example of the template.

    StringConcat('a', 'b', 'c')

    TemplateType

    string

    Yes

    The template type.

    • WHATSAPP

    • VIBER

    WHATSAPP

    CustWabaIddeprecated

    string

    No

    The WABA ID of the ISV customer.

    Note

    This parameter is deprecated. Use CustSpaceId instead.

    65921621816****

    IsvCode

    string

    No

    The ISV verification code, which is used to verify whether the user is authorized by the ISV.

    skdi3kksloslikdkkdk

    CustSpaceId

    string

    Yes

    The Space ID of the ISV sub-customer or the instance ID of the direct customer.

    293483938849493

    AllowCategoryChangedeprecated

    boolean

    No

    Specifies whether to allow Facebook to automatically change the template category. This can improve the template approval rate. This parameter is valid only when TemplateType is WHATSAPP.

    Important

    This parameter is deprecated. WhatsApp no longer supports this parameter.

    true

    MessageSendTtlSeconds

    integer

    No

    The validity period of the template message in WhatsApp.

    • For AUTHENTICATION templates, the value can range from 30 to 900.

    • For UTILITY templates, the value can range from 30 to 43200.

    120

    Response elements

    Element

    Type

    Description

    Example

    object

    The returned data.

    RequestId

    string

    The request ID.

    90E63D28-E31D-1EB2-8939-A94866411B2D

    Code

    string

    The status code of the request.

    • A value of OK indicates that the request was successful.

    • For other error codes, see Error codes.

    OK

    Message

    string

    The error message.

    User not authorized to operate on the specified resource.

    Data

    object

    The returned data.

    {"templateCode": "****4b5c79c9432497a075bdfca36bf5"，"templateName": "hello_whatsapp"}

    TemplateCode

    string

    The template code.

    SMS_232907****

    TemplateName

    string

    The template name.

    hello_whatsapp

    AccessDeniedDetail

    string

    Details about the access denial.

    None

    Examples

    Success response

    JSON format

    {
  "RequestId": "90E63D28-E31D-1EB2-8939-A94866411B2D",
  "Code": "OK",
  "Message": "User not authorized to operate on the specified resource.",
  "Data": {
    "TemplateCode": "SMS_232907****",
    "TemplateName": "hello_whatsapp"
  },
  "AccessDeniedDetail": "None"
}

    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.