Phone calling

Guide to enabling phone calling with the Empathic Voice Interface (EVI).

This guide details how to integrate Twilio with the Empathic Voice Interface (EVI) to enable voice-to-voice interactions with EVI over the phone.

To comply with our Terms of Use, always make it clear that the Empathic Voice Interface (EVI) is an AI. Do not mislead individuals into thinking they are interacting with a human. In addition, developers must comply with the FCC regulation under the Telephone Consumer Protection Act (TCPA), which requires obtaining prior express written consent before calling consumers.

Hume provides a /v0/evi/twilio endpoint that allows you to connect Twilio directly to EVI. This means you do not need run your own server to set up a chat between Twilio and EVI. However, there are currently some limitations with this setup. As EVI is not connecting to your server, you will be unable to transmit the messages necessary for tool use, context injection, or pausing the assistant. If you need these features, you will need to set up your own server that connects to both Twilio and EVI and passes audio between the two; you should not use the /v0/evi/twilio endpoint.

Inbound phone calling

By following the steps below, you can set up a Twilio phone number to connect with EVI.

1

Create Twilio phone number

To set up inbound phone calling, log into your Twilio account at the Twilio Console. Navigate to Phone Numbers > Manage > Active Numbers > Buy a New Number and purchase a phone number of your choice.

A Twilio account is required to access the Twilio console. Should you run into any issues creating a phone number, please refer to Twilio’s documentation.

2

Setup webhook

  1. After purchasing your number, return to the Active Numbers section and select the number you intend to use for EVI.
  2. Create a configuration for EVI by following our configuration documentation, and save the config ID.
  3. Configure the webhook for incoming calls by setting the following webhook URL, replacing <YOUR CONFIG ID> and <YOUR API KEY> with your specific credentials: https://api.hume.ai/v0/evi/twilio?config_id=<YOUR CONFIG ID>&api_key=<YOUR API KEY>.
3

Call EVI

With your Twilio phone number registered, and the EVI webhook set up, you can now give the number a call to chat with EVI.

All of EVI’s core features are available through phone calls. However, phone calls do have two primary limitations:

  1. Latency: transmitting the audio through our Twilio integration adds a few hundred milliseconds, making interactions with EVI slightly slower.
  2. Audio quality: web audio commonly utilizes a higher quality standard of 24,000 Hz. However, due to the compression required for phone conversations, telephony audio adheres to a standard of 8,000 Hz.

Outbound phone calling

An outbound phone call goes “out” from the voice AI to the end user who receives the call. EVI supports outbound phone calling through Twilio’s API, allowing you to automate initiating calls to users. However, this capability comes with important ethical and regulatory requirements:

Outbound calling with EVI requires express prior written consent from users before making any calls. This is mandated by the FCC’s Telephone Consumer Protection Act (TCPA) regulations as of August 7, 2024. The consent must be clear, specific, and documented. Users must be explicitly informed they will receive automated calls from an AI system. Violators are subject to fines of up to $1500 per unauthorized call, liability in civil lawsuits, FCC investigations, and further penalties. Hume takes these requirements seriously and will actively report misuse to regulatory authorities.

Further, outbound calls must comply with the Hume Terms of Use, which includes the Hume Initiative guidelines for empathic AI. For example, manipulative sales calls that take advantage of the user’s emotional expressions to sell products over the phone are prohibited. We monitor for misuses, and violators can be banned from the Hume platform.

Examples of acceptable use cases for outbound phone calls include: scheduled check-ins that users have opted into, appointment reminders, customer service follow-ups, and pre-arranged AI coaching sessions. The key is that these are expected, consented-to interactions that provide value to the user.

The code below shows how to implement outbound calling using the Twilio API. The same EVI webhook used for handling inbound calls can be used for outbound calls: https://api.hume.ai/v0/evi/twilio?config_id=<YOUR CONFIG ID>&api_key=<YOUR API KEY>. Once you create an EVI configuration, you can easily copy this webhook URL in the Deploy tab.

1# Import the Twilio client - run pip install twilio first
2from twilio.rest import Client
3
4# Enter your Twilio credentials from https://console.twilio.com/ and set up the client
5account_sid = "YOUR_ACCOUNT_SID"
6auth_token = "YOUR_AUTH_TOKEN"
7client = Client(account_sid, auth_token)
8
9# Outbound call details
10twilio_number = "YOUR_TWILIO_NUMBER" # Twilio phone number in E.164 format
11to_number = "YOUR_DESTINATION_NUMBER" # Destination number in E.164 format (the number you'd like to call)
12webhook_url = "https://api.hume.ai/v0/evi/twilio?config_id=YOUR_CONFIG_ID&api_key=YOUR_API_KEY" # your EVI webhook URL, the same you'd use for inbound calls
13
14# Make the call while specifying the Webhook URL
15call = client.calls.create(
16    to=to_number,
17    from_=twilio_number,
18    url=webhook_url
19)
20
21# Output call details - should print "Call status: queued"
22print(f"Call status: {call.status}")

Troubleshooting

If you encounter issues while using Twilio with EVI, consider the following troubleshooting tips:

  • Invalid config ID or API key: verify that the config ID and API key used in the webhook URL are correct and active.
  • Exceeded simultaneous connections: if the usage exceeds our rate limits, consider filling out this form to request increasing your concurrent connection limits.
  • Run out of Hume credits: if your Hume account has run out of credits, you may activate billing to continue supporting EVI conversations in your account settings.

If you are interested in volume discounts for EVI, please submit our Enterprise Sales and Partnerships Form.

If you encounter issues using Twilio, you can check your Twilio error logs to understand the issues in more depth. You will find these logs in your console, in the dashboard to the left under Monitor > Logs > Errors > Error Logs. See a list of Twilio errors in their Error and Warning Dictionary.