Chat App Message Service:Send messages via APIs

Preparations

Environment configuration

This example uses Java. For other languages and SDK installation, see Installation Method.

1. Verify Java 8+ is installed. For detailed instructions, see Set up a Java development environment on Windows.

2. Install the SDK by configuring Maven dependencies.

   In your Maven project's pom.xml, add the following to <dependencies> and replace the-latest-version with the latest version number. Then reload Maven dependencies.

   <dependency>
     <groupId>com.aliyun</groupId>
     <artifactId>alibabacloud-cams20200606</artifactId>
     <!-- Replace 'the-latest-version' with the latest version number: https://mvnrepository.com/artifact/com.aliyun/alibabacloud-cams20200606 -->
     <version>the-latest-version</version>
   </dependency>

3. Configure environment variables: To avoid hardcoding your AccessKey pair in code, store credentials in environment variables. After configuration, restart your IDE, command-line interface, and other applications to load the new variables.

4. Configure a proxy (optional). To route requests through a proxy, configure it in the SDK. Proxy configuration.

Basic API information

Review API parameters before making calls. Online Debugging | API Overview

Workflow

1. Create a channel: Go to the Channel Management page.

   1. A channel is the type of path used to send messages. Supported channels: WhatsApp, Viber, Messenger, Instagram, and Email.

   2. Each channel supports only its corresponding message type.

2. Register and bind a WABA: Call the ChatappBindWaba API to bind a WhatsApp Business Account (WABA).

   • You must have a registered WABA before calling this API. WABAs cannot be registered via API—register through the Chat App Messaging Service console.

   • A WABA (WhatsApp Business Account) is required to send commercial WhatsApp messages. Verified WABAs display a badge that increases customer trust and enhances brand image while reducing interference from fraudulent messages.

3. Add a number: Call the AddChatappPhoneNumber API to add a number. This phone number will be used to send WhatsApp messages.

   • You can sync the numbers under your bound and approved WABA with the Business Manager (BM) platform by using the ChatappSyncPhoneNumber API.

   • You can migrate phone numbers from other BSPs to Alibaba Cloud. Migrated numbers retain their display name, quality rating, messaging limits, official business account status, and all previously approved high-quality message templates. Use the CreateChatappMigrationInitiate API to initiate migration.

4. Verify a number: Call the GetChatappVerifyCode API to get a verification code for the number. Then, use the ChatappVerifyAndRegistr API operation to verify the number. After verification, use the GetPhoneNumberVerificationStatus API operation to check the verification status.

   • If you are using a migrated phone number, call the GetMigrationVerifyCode API to obtain a verification code. Then, call the ChatappMigrationVerified API to verify the migrated number.

5. Create and design a template: Call the CreateChatappTemplate API to create a template. After the template is created, it is automatically submitted for review. Then, use the GetChatappTemplateDetail API to query the template review details.

   • Monitor the review status after submission. Reviews typically complete within five minutes but can take over 24 hours.

   • The category of a WhatsApp message template can change automatically during review. When calling the CreateChatappTemplate API, set CategoryChangePaused to true to pause sending when the category changes. WhatsApp message template category changes and sending controls.

6. Send messages: Call the SendChatappMessage or SendChatappMassMessage API to send messages.

   • Ensure your account has sufficient balance before sending. Pricing.

7. View message sending details: Receive reports for sent messages through the ChatAppStatus callback (Simple Message Queue | HTTP URL).

8. Receive mobile originated (MO) messages: Receive inbound messages through the ChatAppInbound callback (Simple Message Queue | HTTP URL).

For more information about API operations, see API overview.

Sample code

The following example sends a message by calling the SendChatappMessage API. Fill in parameters as indicated by the comments.

// This file is auto-generated, don't edit it. Thanks.
package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    /**
     * <b>description</b> :
     * <p>Initialize the client using credentials.</p>
     * @return Client
     *
     * @throws Exception
     */
    public static com.aliyun.cams20200606.Client createClient() throws Exception {
        // For production environment, we recommend a more secure method that does not hardcode the AccessKey. For details, visit https://www.alibabacloud.com/help/doc-detail/2542825.html.
        com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                .setCredential(credential);
        // The service endpoint. For details, visit https://api.alibabacloud.com/product/cams.
        config.endpoint = "cams.ap-southeast-1.aliyuncs.com";
        return new com.aliyun.cams20200606.Client(config);
    }

    public static void main(String[] args_) throws Exception {

        com.aliyun.cams20200606.Client client = Sample.createClient();
        java.util.Map<String, String> templateParams = TeaConverter.buildMap(
                //Replace these with the variable names and values from your template
                new TeaPair("name", "Bob"),
                new TeaPair("sex", "Male")
        );
        com.aliyun.cams20200606.models.SendChatappMessageRequest sendChatappMessageRequest = new com.aliyun.cams20200606.models.SendChatappMessageRequest()
                //Parameters for sending the message.
                .setTemplateParams(templateParams)
                .setTemplateCode("XXXXXXXXXXX")
                .setChannelType("whatsapp")
                .setType("template")
                .setLanguage("en")
                .setFrom("XXXXXXXX")
                .setTo("XXXXXXXX")
                .setCustSpaceId("XXXXXXXXXXX");
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // If you copy this code to run, print the API return value yourself.
            client.sendChatappMessageWithOptions(sendChatappMessageRequest, runtime);
        } catch (TeaException error) {
            // This is for printing and demonstration purposes only. Handle exceptions carefully and do not ignore them in your project.
            // Error message.
            System.out.println(error.getMessage());
            // Diagnostic address.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // This is for printing and demonstration purposes only. Handle exceptions carefully and do not ignore them in your project.
            // Error message.
            System.out.println(error.getMessage());
            // Diagnostic address
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
    }
}

Visit OpenAPI Portal for complete SDK examples in other languages. To make raw API calls, see SendChatappMessage and Signature examples.

Frequently asked questions

• Why is the registration button on the WABA registration page grayed out and unclickable?

• How can I view messages sent by end users to my business?

• Why can't I complete Meta Business Verification when creating a WABA?

• Why are my messages failing to send?

• Can I edit a WhatsApp message template after it is approved?

• Can I delete a WhatsApp message template?

• What should I do if my Facebook account is blocked?

• How do I add an international phone number on WhatsApp?

• What are the rules or restrictions for businesses sending messages from a WhatsApp business number?

• What types of messages does Viber support?

• How do I prepare for sending Viber Business Messages?

• Which countries can I send Viber Business Messages to?

• Can I edit a Viber message template after the template is created?