Store message hashes

Before the Messages app can verify messages from your agent, you need to store your message hashes with Verified SMS. To store a message hash, you need to create the message content hash and send the hash to Verified SMS. By creating hashes on your own infrastructure and sending only hashes via the API, Verified SMS never sees the original message content.

Note: Hash and store both full messages and message segments. If a message content spans more than one SMS message, it's your responsibility to split the content into segments that fit fully within a single SMS message and store hashes based on those segments.

Each Verified SMS endpoint supports 5,000 queries per second (QPS) per partner (not per agent). Requests to store hashes accept up to 10,000 hashes per API call.

When Verified SMS responds to a request to store message hashes, the API returns 200 OK. Once you receive the 200 OK response, you can send your message from any of your sender IDs, and the Messages app can verify the message on the user's device.

If you store a message hash but send the message with a sender ID that isn't associated with your agent, the message doesn't appear as verified. At best, the message appears in a normal, unbranded conversation. At worst, the message might appear as unverified and remove the branding from a different conversation if the sender ID has been claimed by another Verified SMS agent. See how it works and the best practices.

Verification receipts

When you store message hashes with Verified SMS, you can specify postback data that identifies the particular message hash. When the user's device verifies the message, your agent receives a verification receipt with the hash's postback data. See Receive verification receipts.

Caution: Don't include personal information (such as names, phone numbers, or message contents) in postback data.

Prerequisites

Before you begin storing message hashes with Verified SMS,

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. Review the best practices

Configure message hashing

To support the various ways that operators transfer and deliver SMS messages, Verified SMS includes a sample that creates hash values based on common transformations that messages undergo in transit and obfuscate message content.

The Verified SMS Sample, which includes the SDK, is the easiest way to hash message content and store message hashes with Verified SMS. However, it requires configuration.

Note: Google may occasionally update the Verified SMS Sample and SDK to include new hashing algorithms or account for additional in-transit message transformations.

Prerequisites

Before you get started, you need the following software installed on your development machine:

C#

• .NET SDK 2.1 or above

Java

• Java 8
• Apache Maven 3.3.9 or greater or Gradle 5.6.2 or greater

Node.js

• Node.js 10 or greater

PHP

• PHP 7.2 or greater
• php-gmp extension

Python

• Python 3.0 or greater
• virtualenv

Setup

1. On your development machine, download and extract the Verified SMS Sample and SDK.
2. In a terminal, navigate to the sample's root directory.

3. Run the following commands to configure the sample:

   C#

   No configuration necessary.

   Java

   No configuration necessary.

   Node.js

   npm install
   

   PHP

   composer install
   

   Python

   virtualenv env
   source env/bin/activate
   pip install -r requirements.txt
   

Store a message hash

After you configure the Verified SMS Sample and SDK, you can create and store messages hashes.

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:

• Agent ID
• 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

Create and store a message hash

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

   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"
   

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

3. 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]"),
      };
      

   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".

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

5. 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 that hash with Verified SMS.

If you encounter an issue, confirm that you

• configured the Verified SMS Sample and SDK, including installing all prerequisite software
• set the required environment variables
• specified the correct service account credentials
• updated Verified SMS with your agent's current public key

If you continue having issues, contact us.

Next steps

Now that you can create and store message hashes, set up a test device and send a verified message.