Verified SMS lets you verify and brand messages that you send to users. With minimal processing on your infrastructure, you can enhance your conversations with users, build user trust, and prevent scams.
Getting verified
Before you send messages with Verified SMS, you need to create an agent, which controls how conversations with a brand appear to users.
Additionally, you create a private/public key pair for your agent and register its public key with Verified SMS. The key pair enables the agent to use Verified SMS while keeping message content secure.
Eligible users with the Messages app can receive verified messages with Verified SMS. Much like an agent, the Messages app creates private/public key pairs and registers its public key with Verified SMS to keep message content secure.
Once both an agent and a user are registered with Verified SMS, the user can receive verified SMS messages from the agent.
The life of a Verified SMS message
When you send a message with Verified SMS, both your agent and the user's device hash the message content with a shared secret (generated with each others' keys) and send the message hash to Verified SMS. Verified SMS confirms that the message hashes match and notifies the Messages app that the message is verified. The Messages app displays your message in a branded conversation with verification labels.
Looking at it in sequence, your agent performs all its tasks first, then sends the message. Once the user's device receives the message, it performs the same tasks to verify the message.
Agent creates message hashes
When you want to send a verified message to a user, you contact Verified SMS with the user's phone number to get the user's public key. Public keys occasionally rotate, so you need to fetch a user's public key each time you want to send them a message.
With your agent's private key and the user's public key, you use the Verified SMS SDK to calculate a shared secret and convert the message's content into hash values unique to your agent and the user. If the message content is too long to fit into a single SMS, it's your responsibility to split the content into separate messages and create hashes for each message. The SDK obfuscates message content to make it unreadable.
Agent stores hashes and sends the message
After you calculate the message hashes, you call the Verified SMS API to
store the hashes with Google. You authenticate the API call with credentials
that identify your agent. When Google stores the message hash, the Verified SMS
API returns 200 OK.
Once you receive the 200 OK response, you're ready to send the SMS to the user
like you normally would.
User verifies the message
When the user's device receives the SMS, the Messages app identifies your sender ID as a Verified SMS agent and fetches your agent's public key.
With your agent's public key and the user's private key, the app creates a hash of the message content and contacts Google to see if there is a matching hash from your agent. During this time, the user can see that the Messages app is in the process of verifying the message.
If the user's hash matches a stored message hash from your agent, Google sends the verified result to the user's device and sends a verification receipt to the agent's webhook. The Messages app displays the message in a conversation with your agent information, including displaying your agent name below the message itself.
If you send additional messages to the device, the whole process repeats: you fetch public keys and hash message content, and the Messages app verifies each message individually and displays all the messages together in your branded conversation.
Unverified messages
There are three situations in which a user might receive a message that the Messages app can't verify:
- You didn't store the SMS message with the Verified SMS API before sending it.
- You hashed the SMS message with an old private/public key pair.
- The message is an MMS message. Verified SMS doesn't support MMS messages.
- A scammer is spoofing your phone number.
In any of these cases, if the user's device hasn't received verified messages from your agent previously and can't verify the message, the Messages app displays the message in a normal, unbranded conversation just as it would any other message.
However, if the user's device has received verified messages from your agent but can't verify the new message, the Messages app labels the message as unverified and removes some branding from the conversation. Previously verified messages, and any following verified messages, still display your agent logo and include verified sender labels.
Additionally, if a user taps unverified message content (including URLs), the Messages app displays a warning that it couldn't verify the message and an option to report the message as spam.
Conversations without branding
Under certain circumstances, conversations with Verified SMS agents appear without branding. If one or more of the following conditions are met within a conversation, the conversation and its messages lose branding and verification information:
- No verified messages. If you sent messages before you registered with Verified SMS, the conversation doesn't display agent information. After you send your first verified message, the conversation displays agent information.
- One or more RCS messages. Verified SMS doesn't support RCS messages.
Verified messages from two or more agents. If multiple agents send messages from the same sender ID and a user receives messages from at least two of them, the conversation doesn't show information for any of the verified messages or agents.
Additionally, when a user is registered with Verified SMS with one phone number but receives a message from an agent on a different phone number on the same device, the device can't verify the message. In this case, messages that users receive on their registered number are verified normally, but messages that users receive from other numbers don't display branding or verification information.
Two situations can trigger this phone number mismatch:
- The user is on a multi-SIM device. One SIM's phone number may be registered with Verified SMS while the other SIM's phone number isn't.
- The user swapped SIMs. If a user swaps SIMs, the old phone number may be registered with Verified SMS while the new phone number isn't. When the registered phone number and the SIM's phone number match, messages resume displaying branding and verification information.
Hashing and encryption
The Verified SMS Sample and SDK uses a one-way hashing mechanism on message content that makes messages unreadable. Google never sees message contents because Verified SMS compares only message hashes from agents and users.
Communications with Verified SMS—including public key updates, public key retrieval, hash storage, and hash comparisons—are encrypted between Verified SMS agents and Google and between Google and users' devices.
Messages received on users' devices are encrypted by any device-wide encryption that users have configured for their devices and are subject to normal SMS security considerations.
Next steps
Before you begin sending verified messages,
- review the best practices
- create an agent
- configure message hashing
- set up a test device
Once you've done that, you're ready to send a verified message.