Send a verified message

Sending a verified message is a two-step process: first, you store message hashes with Verified SMS, then you send the message content to the user through SMS. Once the user receives the message, the Messages app verifies that the message came from your agent.

Before you verify SMS messages you send to users, confirm that your message verification flow works with a device you manage.

Prerequisites

Before you can send a verified message, you need to

1. Register as a partner
2. Register an agent
3. Create a public/private key pair
4. Update your agent's public key with Verified SMS
5. Configure message hashing
6. Set up a test device

Additionally, you need the ability to send SMS messages from a sender ID associated with your agent.

Hash and store a message

With the Verified SMS Sample and SDK, you can get a user public key, hash a message, and store message hashes all at once.

Note: The following procedure only supports authentication with service account credentials. To authenticate with an API key, see the Verified SMS Sample and SDK's README and samples.

Prerequisites

Before you store a hash, make sure that Verified SMS has your agent's current public key.

Additionally, gather some information:

• Your API key or the path to your service account key on your development machine
• Paths to the agent's private and public keys on your development machine
• The phone number for the device you want to receive the message

Run the sample

1. Configure message hashing on your development machine.

2. Run the following commands to set required environment variables:

   Note: You must export valid environment variables before storing hashes with the Verified SMS Sample and SDK.

   export VERIFIED_SMS_PUBLIC_KEY_PATH="PATH_TO_PUBLIC_KEY.DER"
   export VERIFIED_SMS_PRIVATE_KEY_PATH="PATH_TO_PRIVATE_KEY_PKCS8.DER"
   export VERIFIED_SMS_SERVICE_ACCOUNT_PATH="PATH_TO_SERVICE_ACCOUNT_KEY.JSON"
   

3. Navigate to the sample's root directory on your development machine.

4. Update the sample with the recipient phone number, your message content, and postback data.

   C#

   1. Navigate to "/vsms-csharp-client-v1/".
   2. Open "StoreHashes.cs".

   3. Update sms to the message content as a string.

      For example, change string sms = "Hello, sync world!"; to string sms = "My first hashed message.";.

   4. Update recipientAndMessages with an array of recipient phone number, message content, and postback data.

      For example, change

      List<RecipientAndMessage> recipientAndMessages = new List<RecipientAndMessage>() {
          new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId),
          new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId),
          new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId),
          new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId),
      };
      

      to

      List<RecipientAndMessage> recipientAndMessages = new List<RecipientAndMessage>() {
          new RecipientAndMessage("[phone]", sms, "[phone]", agentId),
      };
      

   5. Save and close "StoreHashes.cs".

   Java

   1. Navigate to "/src⁩/main⁩/java⁩/com⁩/google⁩/communication⁩/businessmessaging⁩/verifiedsms⁩/v1⁩/examples⁩/".
   2. Open "CreateHashesWithCapabilitiesRequestExampleAsync.java".

   3. Update sms to the message content as a string.

      For example, change String sms = "Hello, sync world!"; to String sms = "My first hashed message.";.

   4. Update recipientAndMessages with a mapping of the recipient phone number and the message content.

      For example, change

      List<RecipientAndMessage> recipientsAndMessages =
          new ArrayList<RecipientAndMessage>() {
            {
              add(new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId));
              add(new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId));
              add(new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId));
              add(new RecipientAndMessage("[phone]", sms + "1", "[phone]", agentId));
            }
          };
      

      to

      List<RecipientAndMessage> recipientsAndMessages =
          new ArrayList<RecipientAndMessage>() {
            {
              add(new RecipientAndMessage("[phone]", sms, "[phone]", agentId));
            }
          };
      

   5. Save and close "CreateHashesWithCapabilitiesRequestExampleAsync.java".

   Node.js

   1. Open "store_hashes.js".

   2. Update sms to the message content as a string.

      For example, change let sms = 'Hello, simple post world!'; to let sms = 'My first hashed message.';.

   3. Update recipientAndMessages with an array of the recipient phone number, message content, and postback data.

      For example, change

      let recipientAndMessages = [
        { phoneNumber: '[phone]', text: sms + '1',
            postbackData: '[phone]', agentId: agentId },
        { phoneNumber: '[phone]', text: sms + '2',
            postbackData: '[phone]', agentId: agentId },
        { phoneNumber: '[phone]', text: sms + '3',
            postbackData: '[phone]', agentId: agentId },
        { phoneNumber: '[phone]', text: sms + '4',
            postbackData: '[phone]', agentId: agentId }
      ];
      

      to

      let recipientAndMessages = [
        { phoneNumber: '[phone]', text: sms,
            postbackData: '[phone]', agentId: agentId },
      ];
      

   4. Save and close "store_hashes.js".

   PHP

   1. Open "store-hashes.php".

   2. Update $sms to the message content as a string.

      For example, change $sms = 'Hello, simple post world!'; to $sms = 'Hello, simple post world!';.

   3. Update $recipientAndMessages with an array of recipient phone number, message content, and postback data.

      For example, change

      $recipientAndMessages = array(
          array('phoneNumber' => '[phone]', 'text' => $sms . '1',
                'postbackData' => '[phone]', 'agentId' => $agentId),
          array('phoneNumber' => '[phone]', 'text' => $sms . '2',
                'postbackData' => '[phone]', 'agentId' => $agentId),
          array('phoneNumber' => '[phone]', 'text' => $sms . '3',
                'postbackData' => '[phone]', 'agentId' => $agentId),
          array('phoneNumber' => '[phone]', 'text' => $sms . '4',
                'postbackData' => '[phone]', 'agentId' => $agentId),
      );
      

      to

      $recipientAndMessages = array(
          array('phoneNumber' => '[phone]', 'text' => $sms,
                'postbackData' => '[phone]', 'agentId' => $agentId),
      );
      

   4. Save and close "store-hashes.php".

   Python

   1. Open "create_hashes_example.py".

   2. Update sms to the message content as a string.

      For example, change sms = 'Hello, simple post world!' to sms = 'My first hashed message.'.

   3. Update recipient_and_messages with an array of recipient phone number, message content, and postback data.

      For example, change

      recipient_and_messages = [
          { 'phone_number': '[phone]', 'text': sms + '1',
            'postback_data': '[phone]', 'agent_id': agent_id },
          { 'phone_number': '[phone]', 'text': sms + '2',
            'postback_data': '[phone]', 'agent_id': agent_id },
          { 'phone_number': '[phone]', 'text': sms + '3',
            'postback_data': '[phone]', 'agent_id': agent_id },
          { 'phone_number': '[phone]', 'text': sms + '4',
            'postback_data': '[phone]', 'agent_id': agent_id }
      ]
      

      to

      recipient_and_messages = [
          { 'phone_number': '[phone]', 'text': sms,
            'postback_data': '[phone]', 'agent_id': agent_id },
      ]
      

   4. Save and close "create_hashes_example.py".

5. In a terminal, navigate to the sample's root directory.

6. Run the hashing sample.

   C#

   dotnet build vsms-csharp-client-v1 /p:StartupObject=VerifiedSmsExample.StoreHashes
   dotnet run --project vsms-csharp-client-v1
   

   Java

   Maven

   mvn compile && mvn exec:java -Dexec.mainClass="com.google.communication.businessmessaging.verifiedsms.v1.examples.CreateHashesWithCapabilitiesRequestExampleAsync"
   

   Gradle

   gradle build && gradle -PmainClass=com.google.communication.businessmessaging.verifiedsms.v1.examples.CreateHashesWithCapabilitiesRequestExampleAsync runExample
   

   Node.js

   node store_hashes.js
   

   PHP

   php store-hashes.php
   

   Python

   python create_hashes_example.py
   

The sample script creates a hash of your message content specific to each recipient's phone number and stores those hashes with Verified SMS.

To only create hashes for phone numbers that are Verified SMS-enabled, use capability checks.

Send the SMS message

Now that the message hash is stored with Verified SMS, you're ready to send the SMS message.

1. Send the text "Hello, world!" from your agent's sender ID to your test device as an SMS message.

2. On your test device, open the Messages app.

   You should receive "Hello, world!" as a new message on your device, and the conversation should display your agent's branding information. You may briefly see the message in a pending state while your device verifies the message.

Troubleshooting

If you have issues storing or verifying messages, confirm that you completed all the tasks in Prerequisites. If you continue having issues, contact us.

Next steps

When your device verifies the message from your agent, you're ready and able to send verified messages to your users.