How do I Send SMS Messages to TrueVault Users?

Applications commonly need to contact their users outside the context of the application’s UI, like with an email or text message. However, contact information like a phone number or email address is considered personally identifying information (PII), so you don’t want to ever have that information on your servers, even if it’s only briefly while you’re sending the user an email. By storing your users’ sensitive data in TrueVault, you avoid all the headaches associated with handling that data on your own servers, and with TrueVault’s Messaging API, you can reach out to your users via SMS without ever having their PII touch your servers. (Email is also supported, but we’ll only cover SMS in this guide.)

For this example, let’s suppose you were working on a service for healthcare providers to communicate with patients, and that all PII is stored in TrueVault. One feature you might want to support is sending your users a text message if they have unread messages waiting for hours or days in your service that they haven’t seen yet. We’ll show you how you can build this with the Messaging API.

To get started, you’ll need to make a Twilio account, and of course have a TrueVault account. Once you’ve signed up for Twilio and have access to your account console, you’ll need to create a Twilio-managed phone number. This will be the number that sends an SMS to a user. You can do this in the Manage Numbers section of the Twilio console. We’ll use “+15557778888” to stand in for this number. Next, you’ll need to create a Twilio API Key, which is in the Runtime section of the console. The console will let you create either “Standard” or “Master” keys; a “Standard” key is all that’s needed here. You’ll also need to note the Account SID for your Twilio account.

You’ll also need to know where contact info is stored in the attributes for your users. (You may wish to use a User Schema for this.) For now, we’ll assume that the user’s phone number is stored in the phone field of the attributes, like so:

{
    "phone": "5550001111"
}

How you determine that a user hasn’t read their in-app messages yet is up to you (you might have your web or mobile app notify your service whenever it’s opened, for instance, which would allow you to calculate that someone has received messages but hasn’t opened the app), but for now let’s just assume that you’ve used whatever logic you prefer to determine that a user should receive an SMS informing them to go to your app.

From your server, you would make an HTTP request to the SMS endpoint. You do not need to use authentication information that has admin privileges, and we would encourage you not to do so. Instead, you only need a user authorized for C on User::USERID::Message for the user you’re sending to. Typically this would be done with a “system user” in a group whose policy includes C on User::.*::Message. See this guide and the Groups API for more information.

Once you’ve chosen how you wish to authenticate to TrueVault, decide what message you want to send, and you’re ready to make your request. Here’s what a curl invocation would look like, though presumably you’ll be making this HTTP request from your server code:

curl https://api.truevault.com/v1/users/4a635639-fcf5-4cca-9b79-25376fdb460f/message/sms
    -X POST
    -H 'Content-Type: application/json'
    -u YOUR_AUTH_INFO:
    -d '{
          "provider": "TWILIO",
          "auth": {
            "account_sid": "... your account SID",
            "username": "... your API key SID",
            "password": "... your API key secret"
          },
          "from_number": {
            "literal_value": "+15557778888"
          },
          "to_number": {
            "user_attribute": "phone"
          },
          "message_body": "Please check your HealthCo messages"
        }
        '

If everything is set up correctly, you’ll get an HTTP 200 back, and the user should receive a text message.

For more information on the request and response formats, see the API docs.