APIs are for admins: texting your colleagues with Salesforce Flow (Cactusforce 2021)

15 Jan 2021 🔖 api salesforce flow integration architecture
💬 EN

Thanks for coming to Salesforce MVP Narender Singh’s and my 6-minute lightning demo “APIs are for admins: texting your colleagues with Salesforce Flow” at Cactusforce 2021

(Update: there’s more context for admins at the Salesforce Developers Podcast! Yes, I realize that sounds funny – but APIs are for everybody, so we kept things accessible. Check it out and please share these videos if you learn something!)

---

Twilio

Twilio is a company that, among other things, lets you SMS text message people by sending Twilio commands over the internet.

You can sign up for a free trial without a credit card, and you get about $15 USD of credits to play with. Maintaining a Twilio phone number (from which your text messages will be sent) costs $1.00/month. Each text message sent from a US number to a US number costs $0.01/month, so you should be able to experiment for a few months with your free credits.

Tip: if you have a promo code for bonus credits within a paid Twilio account, consider waiting to upgrade until you’ve run out of free credits. Upgrading Twilio to a paid version removes your remaining free-trial credits.

• Be sure to set up a phone number issued by Twilio.
• Also verify a personal mobile phone number so that Twilio will let you send it text messages while on a free plan.

Now validate that Twilio works at all, before you proceed with Salesforce. Head to Try it Out under Twilio’s programmable messaging.

Be sure to include a plus sign and a country code. Don’t use any punctuation.

• Example: The U.S. White House would be +12024561414, not (202) 456-1414.

---

Named Credentials

Salesforce Flow uses External Service setup records to communicate with 3rd-party APIs. In turn, External Services use Named Credential setup records to clarify where on the internet that API lives.

Named Credentials also store details like which user of a 3rd-party service Salesforce should claim to be (if an API requires authentication).

For this project, create a new Named Credential in Salesforce Setup.

• Give it a simple Label like Twilio Credentials and a simple Name like Twilio_Credentials.
• Fill in the URL as https://api.twilio.com (you might think the schema you’ll work with later would take care of this, but for some reason, you have to say it here, too).
• Leave Certificate blank – that’s for APIs that insist upon Salesforce proving it’s really Salesforce.
• In the Identity Type picklist, choose Named Principal.
  • This means that any Salesforce user allowed to do something that results in our Flow running will log into Twilio’s services as the same Twilio user.
  • Do not use this option with an API whose credentials you actually care about, without first talking to your enterprise security team.
• In the Authentication Protocol picklist, choose Password Authentication.
  • We’re lucky that Twilio offers such a simple way to connect to its API. Some authentication protocols, like OAuth, take a bit more work, and others, like Bearer Tokens, aren’t even supported very cleanly by Salesforce Named Credentials, so you have to carefully research managing secrets within Salesforce to implement Named Credentials with Bearer Token-based APIs.
  • Do not use this option with an API whose credentials you actually care about, without first talking to your enterprise security team.
• In Username, type the Account SID from your Twilio console dashboard.
• In Password, type the Auth Token from your Twilio console dashboard.
• Check Generate Authorization Header because Twilio’s API does indeed expect to find the username and password in HTTP request headers.
• Leave all the other boxes blank and click Save.

---

External Services

Getting an OpenAPI (a.k.a. “Swagger”) schema for your cloud provider is often as simple as asking the company to send it to you, then copying and pasting it into Salesforce as part of an “External Service” setup record.

Using an OpenAPI schema with Salesforce is a lot like copying the “embed code” from a YouTube video and embedding it in a web page. A schema can be hard to write yourself if you’re not an experienced web developer, but hopefully you don’t have to.

Sadly, Twilio’s official schema is a bit newer and longer than Salesforce currently supports (Salesforce is working on it!), so Narender wrote his own OpenAPI schema to teach Salesforce about the part of Twilio’s API that we’re interested in for this demo.

For this project, create a new External Service in Salesforce Setup.

• Give it a simple Name like TwilioAPI and a simple description like External service to facilitate using the Twilio API.
• Set its Named Credential to the one you created earlier.
• Leave Skip unsupported operations checked.
• Scroll down and click the radio button next to Service Schema Complete JSON. Into the box below that radio button, paste the contents of Narender’s schema and click Next.
  • You’d think you could just paste a link to Narender’s schema into Service Schema Relative URL, but you can’t. As far as I can tell, that only works when the schema codebase is published at a URL that starts with the same URL you typed into your Named Credential.
• Review the chart of API operations that Salesforce now knows how to do, so that they look familiar when you see them again in Flow, and click Next, making sure you click through to save your External Service if there are any more prompts.

---

Flow

Now create a new Flow (or find an existing flow and open it in Flow Builder).

• Add an element to your flow, choosing the Action element type.
• In the Search all actions… box, type twil (presuming “Twilio” is in the name of your External Service) and pick the search result called Send SMS or WhatsApp message.
• Give the flow element a meaningful Label like Send an SMS message and a meaningful API Name like Send_an_SMS_message. Describe it if you’d like, too.
• Flip the toggle switches on for all fields under Set Input Values, except leave MessagingServiceSid toggled off.
  • This tutorial didn’t cover setting up different messaging services with Twilio – that’s okay, because the default when you don’t say is to send a text message.
• Enter your Account SID from Twilio into AccountSID (yes, again, even though it was in your username in the Named Credential).
• Enter a message like Hello, just testing into Body.
• Enter your Twilio-issued phone number into From. Be sure to include a plus sign and a country code and to leave out any punctuation.
  • The phone number is available in your Twilio console dashboard.
• Enter the personal phone number you’ve validated with Twilio into To using the same phone number format.
• Click Done
• Design the rest of the flow – for example, you might want to parameterize the SMS inputs with variables, break off the SMS functionality into a subflow, etc.
• Save your flow, giving it a meaningful Flow Label and Flow API Name and Description.
• Activate your flow and click Run.

---

Q&A: Why Flow?

We had a great question in the session today asking:

“Our developers are already building this in Apex right this minute. What advantages might there be to building this in Flow instead?”

As with record-save automations and interactive screen building, in my opinion it really comes down to a question of, “Who is best equipped to maintain this over the years?”

I’d say to give your solution a try in Flow if you have time to play, and if you get stuck, hand it off to a developer. Or race each other and see who builds something first! :) (No cheating, devs – if a Salesforce-compatible OpenAPI schema for an API doesn’t exist, write one for your admin so they have a fighting chance.)

---

Additional resources

The phrase “API” is used to describe many concepts in a Salesforce context. For this Cactusforce session, “APIs are for admins: texting your colleagues with Flows,” we’re talking about option #3, “Call A 3rd Party’s Endpoint Living Outside Salesforce”, in Katie’s Salesforce REST APIs: A High-Level Primer.

All APIs supported by Flow communicate in a standardized fashion over a protocol known as HTTP. It’s pretty simple – check out Katie’s Intro to HTTP.

If you’d like to practice building a Flow with Named Credentials and External Services against a silly, passwordless API before you try a challenge like text messaging with Twilio, visit Katie’s Tutorial: Flow External Services for Salesforce Admins.

If you’re having trouble and you’d like to debug by ensuring that API calls against Twilio account work correctly outside of Salesforce, follow these steps from Twilio using desktop software called Postman, up through the subheading labeled “Sending Your Request.” Postman is the industry-standard point-and-click tool for playing with sending HTTP requests to cloud APIs.

Once you understand HTTP and you’ve learned how to play with requests in Postman, if you’re adventurous, Narender wrote a guide to hand-writing schemas based on an API’s plain-English documentation, like he did for this demo.

For example, you’re welcome to text Twilio back (and Twilio will even auto-reply). However, since Narender’s mini-schema doesn’t include any of Twilio’s API operations for handling received messages, you’ll only be able to see it in your Twilio messaging dashboard or your Twilio SMS logs. Maybe you and a developer can find a part of the API that combs your Twilio incoming message history and expand on Narender’s schema.

Otherwise, Narender’s been busy hand-coding some ready-to-use tiny schemas so you can try Flow with:

• Google’s scanned-document optical character recogntion (OCR) service, Cloud Vision
• YouTube’s video collection
• A COVID-19 statistics portal

Some APIs will require more complex authentication than a simple username and password. Narender wrote a 2-part series on setting up Named Credentials in Salesforce when a 3rd-party API only offers OAuth 2.0 authentication. See part 1 & part 2.

If you’d like to see another Salesforce community member’s take on API usage by admins in Flow with External Services, head over to Charles Stevenson’s presentation at London’s Calling 2020 or Ami Assayag’s & Kirk Steffke’s official webinar.

---

What are you going to build?

Narender and I want to hear what you’re trying to build. We’re both happy to help you work through debugging problems as well. I strongly suspect Liz Skaates and Alex Edelstein from Salesforce would also love to be tagged with examples of your creativity.

Be sure to use the hashtag #Cactusforce2021 – because you heard it at Cactusforce first!