1. Create your app

Make sure to toggle the Phone framework as an initiation when you're creating your app.

Add a capabilities object to your app's config json to choose how Upsales handles calls:

"capabilities": {
   "pickupHook": true,
   "hangupHook": true
}

• pickupHook: Upsales waits for your Pickup webhook before showing the call as answered. Without it, the call is shown as answered 4 seconds after it starts.
• hangupHook: Upsales closes the call when your app sends the Hangup webhook.
• useCallToLinks: phone numbers in Upsales become links with this value as the prefix (for example "tel:"), so the user's computer places the call. Upsales sends /initiate instead of /call.
• noRecordings: Upsales never shows the recording player for your calls.

Learn about phoneCalls in Upsales API

Your app needs to do requests to Upsales API on behalf of your users to list and update phoneCalls objects.

2. Endpoints your app should listen to

As you know from the introduction to Apps in Upsales, we'll make requests to your app to let you know your app is being used. A phone app has the following endpoints to listen to.

/ongoing

To check if there are any ongoing phone calls

/call

When the user starts a new phone call

/initiate

When the user clicks a phone number and your app uses useCallToLinks. The body has the number, clientId, contactId and related object. Upsales does not create a phone call for /initiate: your app creates it with the phoneCalls API and sends the Calling webhook.

/hangup

When the user hangs up the call

/recording

To play a recording of the call (if available). Upsales shows the player when the phone call has a conversationUrl, sends that value to your app as id, and plays the audio your app returns.

3. Webhooks your app should send

For a seamless user experience, make sure your app notifies us of the following events.

Pickup webhook

When a call has been picked up

Hangup webhook

If the call was hung up outside of Upsales

Calling webhook

When a call started with /initiate is being dialed. Send the event phone.calling with the phone call object as data.

Error webhook

When a call could not be made. Send the event phone.error: Upsales shows an error to the user and closes the call.

Send these two the same way as the Pickup webhook.

Feedback? Got any questions or have we missed something that would make your Phone app even better? Let us know at apps@upsales.com