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.

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 algorithims or account for additional in-transit message transformations.

Prerequisites

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

Java

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

Python

• Python 3.0 or greater
• virtualenv

Node.js

• Node.js 10 or greater

Setup

1. On your development machine, download and extract the Verified SMS Sample and SDK

   Java

   Java Sample and SDK

   Python

   Python Sample and SDK

   Node.js

   Node.js Sample and SDK

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

3. Run the following commands to configure the sample:

   Java

   No configuration necessary.

   Python

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

   Node.js

   npm install
   

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.

Confirming your public key

By default, the Verified SMS Sample and SDK runs with debugMode enabled, which confirms that your current public key matches a public key registered with Verified SMS. If the public key doesn't match, Verified SMS returns a 400 INVALID_ARGUMENT error. If you call the API directly, you can validate your public key with the optional publicKey field for agents.storeHashes.

Caution: Confirming your public key increases latency when storing hashes, so only use debugMode or the publicKey field for testing. For production use, set debugMode to false and omit the publicKey field.

Alternatively, you can check your current public key without storing a hash.

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_AGENT_ID="AGENT_ID"
   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 your message content and the recipient phone number.

   Java

   1. Navigate to "/src⁩/main⁩/java⁩/com⁩/google⁩/communication⁩/businessmessaging⁩/verifiedsms⁩/v1⁩/examples⁩/".
   2. Open "CreateHashesExampleAsync.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 recipient_and_messages with a mapping of the recipient phone number and the message content.

      For example, change

      Map<String, String> recipientsAndMessages = new HashMap<>();
      recipientsAndMessages.put("[phone]", sms + "1");
      recipientsAndMessages.put("[phone]", sms + "2");
      recipientsAndMessages.put("[phone]", sms + "3");
      recipientsAndMessages.put("[phone]", sms + "4");
      

      to

      Map<String, String> recipientsAndMessages = new HashMap<>();
      recipientsAndMessages.put("[phone]", sms);
      

   5. Save and close "CreateHashesExampleAsync.java".

   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 a mapping of the recipient phone number and the message content.

      For example, change

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

      to

      recipient_and_messages = {'[phone]': sms}
      

   4. Save and close "create_hashes_example.py".

   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 a mapping of the recipient phone number and the message content.

      For example, change

      let recipientAndMessages = new Map([['[phone]', sms + '1'],
        ['[phone]', sms + '2'],
        ['[phone]', sms + '3'],
        ['[phone]', sms + '4']]);
      

      to

      let recipientAndMessages = new Map([['[phone]', sms]]);
      

   4. Save and close "store_hashes.js".

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

5. Run the hashing sample.

   Java (Maven)

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

   Java (Gradle)

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

   Python

   python create_hashes_example.py
   

   Node.js

   node store_hashes.js
   

The sample script creates a hash of your message content specific to your 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 [e-mail].

Next steps

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