Configure Twilio for SMS

This document explains how to configure SMS notification and messaging services with Twilio and Astralis.

Prerequisites

In order to complete this, you will need the following:

• A valid Twilio account with which to send SMS messages.
• Ability to access and update Astralis system config variables for your Astralis installation. Read about config variables here.
• Astralis OAuth access token with the following scopes.
  • messaging:read: Read an existing messaging configuration.
  • messaging:create_or_update: Create or update messaging configuration.
  • messaging:delete: Delete a messaging configuration.
  • config:read: Read Astralis system configurations.
  • config:update: Update Astralis system configurations.

Getting your Twilio SMS Credentials

In order to configure Twilio as an SMS provider for Astralis you will need:

• Your Twilio Account SID. Follow this Twilio guide to get your Account SID (opens in a new tab).
• Twilio Auth Token. Follow this Twilio guide to get your Auth Token (opens in a new tab).
• You will also need of the following:
  • Your Twilio Messaging Service ID. Follow this Twilio guide to get your Messaging Service ID (opens in a new tab) or;
  • Your Twilio Sender phone number

Example: Set Twilio Messaging as the default messaging provider

To set Twilio Messaging as the default messaging provider, make a PUT request to the api/v1/messaging/default endpoint as follows:

curl '{{FIDES_URL}}/api/v1/messaging/default' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "service_type": "twilio_text"
}'

In the above example {{FIDES_URL}} is the URL to your Astralis server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Astralis access token. The request Content-Type is application/json.

The service_type is twilio_text.

The response to this request will return the configuration for the default messaging provider, including a key as shown below:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "service_type": "twilio_text",
    "details": null,
    "name": "Default Messaging Config [twilio_text]",
    "key": "default_messaging_config_twilio_text"
}

Example: Add Twilio Messaging Credentials

Next, you can add the account SID, auth token and messaging service ID from your Twilio account to your Twilio configuration by making a PUT request to the api/v1/messaging/default/twilio_text/secret endpoint as follows:

curl '{{FIDES_URL}}/api/v1/messaging/default/twilio_text/secret' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "twilio_account_sid": "{{TWILIO_ACCOUNT_SID}}",
    "twilio_auth_token": "{{TWILIO_AUTH_TOKEN}}",
    "twilio_messaging_service_sid": "{{TWILIO_MESSAGING_SERVICE_ID}}"
}'

In the above example {{FIDES_URL}} is the URL to your Astralis server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Astralis access token. The request Content-Type is application/json.

The {{TWILIO_ACCOUNT_SID}} is your Twilio ACCOUNT SID, {{TWILIO_AUTH_TOKEN}} is your auth token and {{TWILIO_MESSAGING_SERVICE_ID}} is your messaing service ID as created in this section.

The response to this request will be a confirmation message that the secret has been updated for the configuration identified by the key as shown in this example:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "msg": "Secrets updated for MessagingConfig with key: default_messaging_config_twilio_text.",
    "test_status": null,
    "failure_reason": null
}

Messaging Config Variables

Astralis allows you to configure which messaging service is used to send system notifications. To do this you must update Astralis' system-wide settings to ensure that your Twilio service is selected. You may also configure what kinds of notifications Astralis will send.

Below is a list of the notification configurations that can be set:

Example: Set Messaging Config Variables

You can update your Astralis messaging configuration by making a PATCH request to the api/v1/config endpoint as follows:

curl '{{FIDES_URL}}/api/v1/config' \
-X PATCH \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
  "notifications": {
    "notification_service_type" : "twilio_text",
    "send_request_receipt_notification": true,
    "send_request_review_notification": true,
    "send_request_completion_notification": true
  },
  "execution": {
    "subject_identity_verification_required": true
  }
}'

In the above example {{FIDES_URL}} is the URL to your Astralis server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Astralis access token. The request Content-Type is application/json.

The notification_service_type value is twilio_text and for each of the notifications you wish to send via Twilio, set their value to true. You can also enable or disable subject identify verification on privacy requests here by settting execution.subject_identity_verification_required to true. Learn more about Subject Identify Verification here.

The response to this request will confirm the service type and the current status for each notification as shown in the example below:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "notifications": {
        "send_request_completion_notification": true,
        "send_request_receipt_notification": true,
        "send_request_review_notification": true,
        "notification_service_type": "twilio_text"
    },
    "execution": {
        "subject_identity_verification_required": true
    }
}

Check the messaging configuration status

To check that your messaging configuration has been fully configured, you can invoke the status endpoint at /api/v1/messaging/default/status.

curl '{{FIDES_URL}}/api/v1/messaging/default/status' \
-X GET \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d ''

If everything is correctly configured you will receive a response similar to the example below with config_status of "configured".

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "config_status": "configured",
    "detail": "Active default messaging service of type twilio_text is fully configured"
}