Skip to content

Latest commit

 

History

History
124 lines (83 loc) · 7.64 KB

README.md

File metadata and controls

124 lines (83 loc) · 7.64 KB

Twilio Serverless Frontline Integration Service

Twilio Frontline Integrations Service

This repository implements a Twilio Frontline integration service using Twilio Serverless with Airtable as the contact databse.

⚠️ Not an official Twilio Project: this software is not owned or maintained by Twilio. There is no Twilio support SLA for this integration.

⚠️ Scaling limits: Airtable's API has a maximum throughput of 5 requests per second. This product is not suitable for large teams, see the Integration Limits section for more details.

Prerequisites

We recommend following the setup outlined Frontline node.js quickstart, which shows you how to do the following:

Once you reach the step to "Configure the Frontline Integration Service" you are ready to deploy this app.

Project Setup

Follow these steps to clone the repository, install dependencies, and set environment variables:

# Clone the repository:
git clone

# Change to the project directory:
cd frontline-airtable-quickstart

# Install dependencies:
npm install

# Copy the sample environment variables file to .env:
cp .env.example .env

Environment Variables Reference

Here are the environment variables that must be configured for the app to run:

ACCOUNT_SID= # Your twilio account SID, found in the console.
AUTH_TOKEN= # Your auth token, found in the console.

SSO_REALM_SID= # Go to console > Frontline > Manage > SSO/Log in

TWILIO_SMS_NUMBER= # SMS enabled phone number in e164 format (e.g. +14135551234)
TWILIO_WHATSAPP_NUMBER= # A Twilio WhatsApp sender, if you have one.

AIRTABLE_API_KEY= # Your Airtable API key
AIRTABLE_BASE_ID= # Your Airtable Base ID

Deploy

Deploy this Serverless app with one command:

twilio serverless:deploy

ℹ️ Always deploy to the same Twilio Account as your Frontline Service: This integration service uses Twilio-signed requests to protect the callback URLs. The callback URLs will reject requests from a different Twilio account with a 403 error. You can check which account you're deploying to with twilio profiles:list and add another account with twilio profiles:add.

If your deploy is successful, you should see an output that looks like this: Screen Shot 2022-03-02 at 4 32 36 PM

The app provides five callback URLs:

  • /callbacks/crm: called when Frontline loads the contact list or a user detail page.
  • /callbacks/outgoing-conversation: called when a user initiates an outbound conversation.
  • /callbacks/routing: called when a messages is sent inbound that does not match an open conversation.
  • /callbacks/templates: called when a user opens the templates menu.
  • /callbacks/twilio-conversations: called after a conversation is created or a participant is added to the conversation.

Configure Callbacks

Copy and paste the callback URLs (uncluding your unique subdomain) into your Frontline configuration in the console.

Routing configuration

In the Twilio Console, go to Frontline > Manage > Routing and add [your_app_url]/callbacks/routing under Custom routing: Screen Shot 2022-02-28 at 11 43 02 PM

General callbacks

In the Twilio Console, go to Frontline > Manage > Callbacks and copy / paste the following callback URLs from your Frontline integration service:

  • CRM Callback URL: [your_app_url]/callbacks/crm
  • Outgoing Conversations Callback URL: [your_app_url]/callbacks/outgoing-conversation
  • Templates Callback URL: [your_app_url]/callbacks/templates

Screen Shot 2022-02-28 at 11 42 24 PM

Conversations Setup Callbacks

This callback receives the onConversationAdded and onParticipantAdded events from the Conversations service and sets the name of the conversation as well as the participant and participant avatar that is joining the conversation.

To set them up, go to Conversations > Services > Default Frontline Service > Webhooks. Then select the onConversationAdded and onParticipantAdded events.

Data Format

A sample Airtable template can be found here.

Note that addresses in the sms and whatsapp columns must be in e164 format, e.g. +1234567890. If numbers are formatted differently, the integration may fail to find customers in Airtable when a conversation is initiated from an inbound message.

Integration Limits

We don't recommend using this integration to support more than 30 Frontline users and/or more than 4000 contacts. Here are the details to know:

Airtable's API has a maximum throughput of 5 requests per second. This integration service generates a request to Airtable under the following conditions:

  • When a user opens the contact list the first time, or refreshes the contact list after the Twilio Serverless instance has "cooled off". Multiple API calls may be generated if more than 100 contacts are returned.
  • When a user opens a customer profile page.
  • When a user opens the templates menu from the mesage compose input.
  • When a new customer texts inbound and creates a new conversation.

Additionally, Twilio Functions has the following limits:

  • Functions may not run for longer than 10 seconds.
  • You can't have more than 30 function invocations running concurrently.

Contact Data Caching

Since pulling in a large list of contacts is the most data-intensive operation against Airtable, we cache contact data between Twilio Serverless invocations. You can see the implementation of the caching mechanism here.

Each time a user refreshes, we check to see if a contact list is stored in memory from another Serverless invocation. If there's nothing in memory, we do a pull of all contacts for that Frontline worker. If there is a replica stored in memory, we query Airtable for any records added after the last data pull, and then append those to the list of contacts. Twilio Serverless retains the cache of contacts for about 5 minutes, reducing the need to pull data from Airtable and speeding up interactions for Frontline users.

Integration Limits tl;dr

If you are returning a large contact list to users, your Twilio function may time out before Airtable returns all the pages of the query results.