Chat App Message Service:Send messages using APIs

Preparations

Environment configuration

This topic uses Java as an example. For other languages and their SDK installation methods, see Installation Method.

1. Check your Java environment: Your Java version must be Java 8 or higher. For detailed instructions, see Build a Java development environment in Windows.

2. Install the SDK by configuring Maven dependencies.

   In the pom.xml file of your Maven project, add the following information to the <dependencies> tag and replace the-latest-version with the latest version number. After you save the file, reload the 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 your code and prevent leaks, we recommend configuring environment variables and reading the AccessKey pair from them. After configuration, restart or refresh your development environment, including your IDE, command-line interface, and other applications, to ensure the new environment variables are loaded.

4. Configure a proxy (optional). To access the service through a proxy server, configure the proxy using the SDK. For more information, see Proxy configuration.

Basic API information

Read the API parameter specifications and usage instructions 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. WhatsApp, Viber, Messenger, Instagram, and Email channels are supported.

   2. Select the appropriate channel type, as each channel can only send its corresponding message type.

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

   • Before calling this API, you must already have a registered WABA. You cannot register a WABA via the API. If you do not have one, register it through the embedded page in the Chat App Messaging Service console.

   • A WABA is an official business account that enterprises must register to send commercial WhatsApp messages. A WABA verified by WhatsApp receives a verification badge, which 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.

   • The number migration feature allows you to migrate phone numbers registered with other BSPs to Alibaba Cloud. The migrated number will retain its original display name, quality rating, messaging limits, official business account status, and all previously approved high-quality message templates. Use the CreateChatappMigrationInitiate API to initiate the 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.

   • After the template is submitted for review, monitor its review status. The review is typically completed within five minutes but can occasionally take more than 24 hours.

   • The category of a WhatsApp message template can be automatically changed during the review process. When you call the CreateChatappTemplate API, you can set the CategoryChangePaused parameter to true to pause sending when the category changes. For more information, see Add send control when WhatsApp message template category changes.

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

   • Before sending, make sure that your account has a sufficient balance. For more information, see Chat App Message Service 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 sample code shows how to use the SDK to send a message by calling the SendChatappMessage API. Fill in the parameters according to 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);
        }
    }
}

You can visit OpenAPI Portal to view complete SDK request examples for various languages. If you want to encapsulate to make API calls, see SendChatappMessage and Signature examples.

FAQ

• Why is the register button on the WABA onboarding page unavailable?

• 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?