HomeTutorialsAPI Reference
Tutorials

Twilio

Configure the OptiPub Twilio Integration

Suggest Edits

📘

OptiPub Integrations

Integrations can be found in OptiPub > Administration > System Settings > Integrations

Activate the Twilio Integration

  1. Click Add on the Twilio integration card from the Integrations page in OptiPub.

  2. Retrieve the API Token, Twilio Account SID, and Messaging Service ID from the Twilio Console.
    1. API Token - Twilio > Account Admin > Account Management > API Keys & tokens
    2. Twilio Account SID - Twilio > Account Admin > Account Management > General Settings
    3. Messaging Service SID - Twilio > Develop > Messaging Services

  3. The Prefix is for a Brand Name, such as OptiPub or OptiPub Alerts.

  4. The Help Text should include contact information, message frequency, and associated message and data rates. For more help, contact support at [[email protected]] or call [1-800-123-4567]. Msg & data rates may apply.".

  5. The Stop Text should include confirmation of opt-out, and directions to opt back in, such as You have successfully opted out. You will not receive any more messages from this number. Reply START to resubscribe.

Read the Twilio documentation for Getting started with Messaging Services.

You will need to:

  1. Create a Twilio Messaging Service.
  2. Purchase or Port Phone Numbers to your Twilio account. (Guide Below)
  3. Configure the Messaging Service Integration with Webhooks to your OptiPub account. (Guide Below)
  4. Complete Twilio A2P Registration to create a Brand and Campaign, review the Twilio documentation links provided. (Guide Below)
  5. Connect Phone Numbers to the Messaging Service. (Guide Below)
  6. Setup Twilio Link Shortening. (Guide Below )

OptiPub Twilio Integration

Configure the Webhook in Twilio Messaging Services

Configure the webhook in Twilio > Develop > Messaging > Services > [Service Name] > Integration.

The Twilio Messaging Service uses a webhook to forward incoming SMS messages to OptiPub.

Select the 'Send a webhook' radio button.

  • Add the URL - https://{APP_DOMAIN}/auth/twilio- to both Request URL and Fallback URL and select HTTP Post from the drop down options.
  • Click [Save]

Twilio Webhook

The Twilio Webhook forwards all message, and notifies OptiPub if the Twilio configured Keywords for Opt-in,Opt-out, or Help are matched.

OptiPub will auto-reply with the corresponding messages configured in the OptiPub Twilio Integration.

View the configured Keywords in the Twilio Campaign configuration from Twilio > Develop > Messaging > Regulatory Compliance > Campaigns > [Campaign Name]

Twilio Webhook Keywords

Twilio SMS Configuration

Purchase Twilio Phone Numbers

Twilio > Develop > Phone Numbers > Manage > Active Numbers

You can purchase 10-digit phone numbers as well as Toll-Free phone numbers.


Configure Incoming Messages to use the Messaging Service

Select an Active number and in the Configure tab navigate down to Messaging Configuration.

Choose a Messaging Service to use for incoming messages for the phone number.


Twilio A2P 10DLC Compliance (10-digit long codes)

Review A2P 10DLC Campaign Approval Requirements in the Twilio Documentation


A2P 10DLC Registration

Twilio must manually verify applications which can take a few days or up to a few weeks to complete.

Required Information

Registration requires your Federal EIN (Employer Identification Number), company name, address, website, contact information, a detailed description of how you plan to use the short code (e.g., marketing, customer service), opt-in procedures, terms of service, privacy policy

Twilio > Develop > Messaging > Regulatory Compliance > Onboarding

Navigate in Twilio's Console to the Compliance Onboarding page to start registering an A2P 10DLC Campaign:

  • Create a Customer Profile
  • Register Brand
  • Campaign Registration (a Messaging Service will be linked during this step)
  • Register and Connect existing Phone Numbers to the Campaign

Brands are used to configure a brand identity and create Campaigns.

Campaigns connect a Brand, Messaging Service, and Phone Numbers.

Phone Numbers must be connected to both the Campaign and the Messaging Service.

Messaging Services are used by the Twilio API to identify your configuration and process incoming and outgoing messages.


Review A2P 10DLC Registration steps in the Twilio Documentation and Campaign Use Cases


Campaign Approval Requirements

Call-to-Action / Opt-In Forms

Call-to-Actions should contain the following information:

  1. Identify the publication or service being subscribed to.
  2. Identify purpose of messages (e.g., product updates, event reminders, marketing and promotional offers).
  3. Clear opt-in and consent procedures.
  4. Message frequency and any associated fees or charges.
  5. Link to Privacy Policy.
  6. Optional link to other applicable terms and conditions (e.g., how to opt-out, customer care contact information)

📘

Opt-In Consent Example

By providing your phone number you agree to receive marketing and promotional text messages from {Publication Name}. Consent is not a condition of purchase. Message frequency varies. Message & data rates apply. Reply HELP for help or STOP to cancel anytime. [Link to Privacy Policy] [Link to Terms and Conditions].


Initial Opt-In Confirmation Message

The confirmation message is composed using the Twilio Integration configuration.

The SMS confirmation message should include:

  1. Identify Branding. (The integration '[Prefix]' configured is prepended to every message)
  2. Identify the publication or service being subscribed to. ('You're now subscribed to alerts!)
  3. Available support contact information: phone number and email address. (The integration Help Text configured)
  4. Message frequency and associated fees or charges. (The integration Help Text configured)
  5. Clear opt-out instructions. ('Reply STOP to Opt-Out' is appended to every message)

📘

Opt-In Confirmation message

[{Prefix}] You're now subscribed to {Subscription->Publication} alerts! {Help Text}. Reply STOP to Opt-Out


Configuring Help Text

Include contact information, message frequency, and associated message and data rates in the integration's Help Text configuration.

📘

'HELP' Response message

[{Prefix}] {Help Text}. Reply STOP to Opt-Out


Website Privacy Policy

A compliant Privacy Policy must state that no mobile information will be shared with third parties/affiliates for marketing/promotional purposes. Twilio Documentation

Information sharing to subcontractors in support services, such as customer service is permitted.

Opt-in and consent information cannot be shared for any reason to 3rd parties.


Connect Phone Numbers to Messaging Service

Twilio > Develop > Messaging > Services >

Select a Messaging Service > openSender Pool from the left menu > click Add Senders

Add a Phone Number or a Short Code


A 10DLC phone number must be connected to both the Messaging Service it's assigned Campaign.

Short Codes do not need a compliant brand and campaign.


Send a test SMS from OptiPub

Once you have completed the steps above and your Brand is registered and your Campaign is verified, you are ready to send a test SMS message in OptiPub.

After configuring Twilio Link Shortening and have enabled Shorten URLs in the OptiPub Twilio Integration, send a test message with a link in the content to confirm links are being replaced with shortened links.


Twilio SMS Link Shortening and Click Tracking

Twilio Documentation - Link Shortening Features and Link Shortening Onboarding Guide

Twilio Link Shortening replaces URLs in SMS messages with shortened links using a company-branded domain. These links route through Twilio to track engagement before redirecting to the original URL.

OptiPub receives click event callbacks from Twilio, and maps statistics to OptiPub messages and subscriptions.

Enable Shorten URLs in the OptiPub Twilio Integration to activate click tracking and link shortening. But first, Twilio must have a verified domain set up and links shortening configured in the messaging service.


📘

OptiPub Managed Link Shortening

If OptiPub manages your Twilio account, provide a subdomain you own to OptiPub to use as the link shortening subdomain, and OptiPub will manage the Twilio configuration.

Follow this guide to Delegate the Subdomain to OptiPub for Sending Email, you will use the same process to delegate your link shortening subdomain to OptiPub.

Contact support via your Slack channel, or by emailing [email protected].


Verify a domain in Twilio Admin Console

Choose a new and unused subdomain from a domain that you own to use with Twilio link shortening. Preferably use a short domain so links in your SMS messages use less characters against the 160 character message segment size.
(e.g., m.opti.pub)

Twilio Messaging Services only support one domain per service, so use a domain related to your organization and not a specific publication.

A Twilio Organization administrator is required to perform this setup, if OptiPub is managing your Twilio account, work with OptiPub support to setup


Add a Domain

From the Twilio Web Console, use the Admin dropdown in the top right and click on Twilio Admin, then open Domains from the left menu and click the button Add Domain.

  1. Enter the link shortening subdomain, then click Save & continue.
  2. Choose DNS verification, then click Save & continue.
  3. Create a TXT DNS record with your DNS provider using the TXT record value provided. Prepend _twilio. to the chosen subdomain for the name of the record. (e.g., _twilio.m.examp.le for m.examp.le)
    1. TXT record -
      _twilio.m.examp.le. TXT twilio-domain-verification=e67dcb6dxxxxxxxxxxxxxxxxxxxxxxxx 3600

  4. Click the button Verify Domain.

After successful verification, the Twilio Admin > Domains tool will show a Verified status for the subdomain. You will need to create more DNS records below so stay logged into your DNS provider.

Twilio Domain Verification

Configure Link Shortening in Twilio

While configuring Link Shortening in Twilio, you will create DNS records to point your domain to Twilio's link shortening servers.

OptiPub recommends using a brand new subdomain with no existing DNS records so you are able to create a CNAME record.

If you are unable to create a CNAME record on the subdomain, then for the same subdomain, create a separate A record for each IP.


Link Shortening Configuration

Twilio > Develop > Messaging > Services >

Select a Messaging Service > open Link Shortening from the left menu

  1. Choose a Domain and click Save changes
  2. Create DNS record(s) to point your subdomain to Twilio's link shortening servers.

    1. CNAME record - m.examp.le. CNAME lsct.ashburn.us1.twilio.com. 3600
    2. If unable to create a CNAME record, create A records for each IP instead:
      1. A record - m.examp.le. A 3.233.187.46 3600
      2. A record - m.examp.le. A 3.233.108.250 3600
      3. A record - m.examp.le. A 54.157.2.211 3600

  3. Click the button Validate and confirm you see DNS validation successful.
  4. Select Twilio-managed certificate under Certificate management and click Continue to confirm the pop-up message.
    Twilio will take a couple minutes to create the certificate. Continue with configuration, but confirm the certificate completes with processing before sending a test message.

  5. Domain fallback URL - choose a URL for broken or expired links to fallback to. Use a link or offer expired webpage if you have one, or use your website's home page.
  6. Click tracking callback URL - Use the same callback url for click events that is used for message status events.
    1. Callback URL - https://{APP_DOMAIN}/auth/twilio (e.g., https://[client].app.optipub.com/auth/twilio)

  7. Disable "https://" prefix - [check] yes, this will shorten the url in SMS messages.
  8. Deliver messages anyway in case of Link Shortening failure - [check] yes, we want messages to send even if link shortening fails.

Click Save

After saving create an SMS test message in OptiPub with a link included in the content. On reception of the SMS message, confirm the link was replaced with the link shortened domain (e.g., m.optipub.com/t3eR9Tj2oP) and the link redirects correctly to the original URL.

Twilio Link Shortening

Twilio phone number types

Both Short Codes and A2P 10DLC SMS phone numbers have an application process that can take up to a few weeks for verification.

Twilio provides 2 types of phone numbers for sending SMS - Short Codes and 10DLC (10-digit long codes).

Short Codes have a high quarterly fee that can cost well over $10,000 per year.

Short codes can only send outgoing messages to US phone numbers, they cannot receive incoming messages but can only process keywords from incoming messages.

Their advantage used to be that they can send outgoing messages at a rate of 100/second with no daily limit, but Trusted A2P Brands now have comparable outgoing sending rates and limits in Twilio.

A2P 10DLC Compliance is now required for sending outgoing SMS with Twilio using 10-digit phone numbers.

10DLC (10-digit long code) phone numbers have a minimal monthly lease cost, and can fully process incoming messages, and are able to send outgoing domestic and international messages.

Outgoing sending rates are determined by your A2P Brands Trust Score. A decent score can send 40/second per carrier, while a perfect score can send over 250/second.

Review Twilio A2P 10DLC Message Throughput for outgoing message rates and limits for different Campaign Types and Brand Trust Scores.

Review Twilio Pricing for per-message rates and carrier fees, and phone number lease charges.


Toll-free 10DLC

Toll-free numbers can be used like standard A2P 10DLC phone numbers, but they require an additional verification process.

The verification process is more strict, and requires much of the same information as a Camapaign.

Review Twilio's Toll-free Verification Onboarding Guide Twilio Documentation.


Short Code Senders

Twilio must manually verify applications which can take a few days or up to a few weeks to complete.

Required Information

Registration requires your company name, address, website, contact information, short code use case, opt-in procedures

Twilio > Develop > Messaging > Senders > Short Codes > +[Apply for a New Short Code]

Complete the US Short Code Application and Submit for review.

Review more Short Code information in the Twilio Documentation.


Short Code Opt-Out Management

Twilio > Develop > Messaging > Services >

Select a Messaging Service > open Opt-Out Management from the left menu

Opt-Out Management can be configured for all messaging services by clicking the button Enable Advanced Opt-Out.

Short Codes require Advanced Opt-Out to be enabled in the Messaging Service for Twilio to handle opt-out response messages. Otherwise opt-outs must be managed externally of Twilio.

Review Twilio's guide to Getting Started with Advanced Opt-Out Twilio Documentation

Updated 5 days ago