Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Push Inbound Messages and Status Updates to Salesforce

Many of the events that occur during a message lifecycle, such as delivered or failed are asynchronous. Twilio typically sends these events as a POST request to a webhook that you specify in the Twilio Console. Status updates give you insight in Salesforce for which messages have succeeded or failed.

For Salesforce, we use a Connected App, plus a Twilio Function to authenticate and post data back into Salesforce. The chain of events is as follows:

  1. One of your phone numbers receives a new message or message status update.
  2. The messaging service (your number pool) invokes a Twilio Function.
  3. Your Twilio Function authenticates to Salesforce via credentials from a Connected App.
  4. Salesforce creates a new message object (for inbound messages) or updates an existing message with a status.

Flow diagram for Twilio and Salesforce interaction

Setting up message status updates should take about 20 minutes. By the end of this setup, you will have message status data captured in Salesforce. We'll finish with a report on our messages that shows which were delivered or undelivered.

Create a Salesforce API User

We strongly recommend creating a Salesforce API user to use with your Connected App as a good security practice. In the event that your Connected App credentials are exposed, an API user will limit an attacker's ability to access your organization's user interface and act as an administrator. You can follow Salesforce's full documentation here. The steps are:

  1. Create a normal user with appropriate licenses. You may also consider giving them a new specific profile.
  2. Go to Setup -> Manage Users -> Profiles.
  3. Open the profile of the new User. Click Edit.
  4. Scroll down to Administrative Permissions and check the API Enabled box.

Any team member (developer or administrator) that you add to your Twilio Console project will be able to view your API User's credentials. We recommend restricting Twilio Console access to only the necessary team members and enabling 2FA for your Twilio account.

Create a Salesforce Connected App

  1. Use Salesforce to create a new Connected App.
    • In Lightning Experience, use the App Manager to create Connected Apps. From Setup, enter 'App' in the Quick Find box, then select App Manager. Click New Connected App.
    • In Salesforce Classic, from Setup, enter Apps in the Quick Find box, then select Apps (under Build | Create). Under Connected Apps, click New.
  2. Enter the name of your application.
  3. Enter the contact email information, as well as any other information appropriate for your application.
  4. Select Enable OAuth Settings.
  5. Enter as the callback url.
  6. Select Access and manage your data (API) to Selected OAuth Scopes.

Create a Salesforce Connected App with Twilio

  • Click Save. You will see an alert that the connected app could take 2-10 minutes for the changed to take effect. Click Continue.

Connected App success messaging in Salesforce

  • The Consumer Key is created and displayed, and the Consumer Secret is created (click the link to reveal it).

Connected App Credentials.png

You've successfully created your Salesforce Connected App. Continue to the next step.

Create a Twilio Function

In this step, we'll create a Twilio Function to authenticate with our Salesforce Connected App. This will allow us to send data to Salesforce whenever we receive an inbound message or status update.

We've already created a Function template for you to use, so there's no coding necessary. Just add the the values from your connected app with your Salesforce login information.

  1. In a new tab, visit the functions page in the Twilio Console.
  2. Click on the red "+" button to add a new function.
  3. In the modal that opens, click on "Connect to Salesforce".

Choose Template.png

Next, you'll see a list of configuration variables for your function. Fill them out with the values specified in the table below.

Specify Variables.png

For the user associated with SF_PASSWORD, SF_USERNAME, and SF_TOKEN, use the credentials that you generated when creating your API user.

Important: if you're configuring in a production Salesforce organization, make sure to provision a Twilio for Salesforce license to the user whose credentials are being associated here. The setup guide describes how to provision licenses.

Key Value
SF_IS_SANDBOX Set to true if you're testing in a sandbox organization (your organization's URL starts with Otherwise set to false.
SF_CONSUMER_KEY The Consumer Key from your connected app.
SF_CONSUMER_SECRET The Secret Key from your connected app. Click the link in Salesforce to reveal your Secret Key.

A Salesforce Password. This can be a personal password, but we recommend using a system user's username.

If you are configuring in production, make sure that this user has a Twilio for Salesforce license assigned.


A Salesforce Username. This can be a personal username, but we recommend using a system user's username.

If you are configuring in production, make sure that this user has a Twilio for Salesforce license assigned.


A Salesforce Security Token. This can be a personal token, but we recommend using a system user.

If you have forgotten it, you will need to reset it. Visit the salesforce instructions for details.

Once you've added your configuration variables, click the red "Create" button. You will be directed to a Function page that looks like this:

Twilio function example to push SMS status updates to Salesforce

Connect your Twilio Function to the Messaging Service

Finally, ensure that your Twilio Function runs whenever your messaging service (pool of numbers) sends a status callback or receives an inbound message.

  • In your Twilio Function from Step 2, copy the function path (containing your function's unique URL):

Copy Function Link.png

  1. In a new tab, go to the Messaging Services page in your Console.
  2. Open the Messaging Service that you created during your initial set up, and go to the "Outbound Settings" section of the page.
  3. Paste your Twilio Function URL in two places:
    1. The Request URL input under "Inbound Settings".
    2. The Status Callback URL input.
  4. Click the "Save" button at the bottom of the page.

Paste Function Links.png

Test and Verify

Note: Salesforce Connected Apps can take 2-10 minutes to provision. If you try to test your function immediately after you provision the connected app and receive an authentication error, wait 10 minutes and try again.

To test that your Function is working properly, open your Function page (click on your Function from the list). Then, try sending an SMS to your Salesforce phone number.

If you've successfully set up your Function, you should see the following log message with "Success Getting Token" appear below your Function:

Successful Function.png

Common Pitfalls

Error Solution
I didn't see any logs when I texted my number. Nothing happened. Check that you have the correct links set in Step 3. Be sure to click “Save” on your Messaging Service page to update your configuration.
Error Getting Token:{"error":"invalid_grant","error_description":"authentication failure"} This error indicates an issue with your login credentials. Check that your variables SF_IS_SANDBOX, SF_USERNAME, SF_PASSWORD, and SF_TOKEN values from step 2 are correct.
Error Getting Token:{"error":"invalid_client_id","error_description":"client identifier invalid"} Your function is successfully authenticating with your username and password, but your SF_CONSUMER_KEY is not correct. It should be 85 characters long, including letters, numbers, and symbols.
Error Getting Token:{"error":"invalid_client","error_description":"invalid client credentials"} Check that your SF_CONSUMER_SECRET is correct. It should be a 19 digits long and only include numbers.

Step 5: Report on Your Messages!

Now that you've set up your status callback system, you can create a report on the statuses of our messages.

  1. In the reports tab, create a new report.
  2. Click on "Other Reports" then select "Messages" as the object to report on.

Other Reports

From here, add the "Body" and "Status" columns to your report:


Next, try sending some messages to make sure you're getting updates. Text your own phone for a successful delivery, then try creating a contact with one of Twilio's test numbers to see an undelivered status.

Wrap Up

Congratulations! You've now successfully captured message deliverability within Salesforce. Now that you have a Twilio Function set up, you can re-use this pattern to post data into Salesforce.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.