Menu

Phone Number (Twilio)

Phone number for an agent (Twilio, beta)

With a phone number your agent becomes reachable by call. When someone dials the number, the agent picks up, speaks with the configured AI voice and answers questions in real time, just like a live call in the chat. The transcript, billing and a conversation entry land in the history automatically, exactly like a browser call.

Beta feature: Telephony is marked as beta and enabled per account. You need a Twilio account with a phone number. If the Audio & Voice section shows no phone number field, the feature is not yet active for your account. Contact our support in that case.

Requirements

  • Audio features are enabled for the agent (tab Audio & Voice, toggle Audio features).
  • Your account is enabled for the voice/telephony beta.
  • You have administrator or superadmin rights (only these roles see the Phone number and Twilio Auth Token fields).
  • You own your own Twilio account with a Twilio number that supports voice calls.

How it works

  1. Twilio receives the call on your number.
  2. Twilio sends a webhook (HTTP POST) to hermine.ai.
  3. hermine.ai uses your Twilio Auth Token to verify the call genuinely comes from your Twilio account, resolves the dialed number to the matching agent and connects the call to the voice assistant.
  4. Caller and agent talk live. After hanging up, the transcript is available as a phone conversation.

You bring your own Twilio account (bring your own Twilio): the number and the auth token are yours, and Twilio billing runs through your account. hermine.ai only needs the auth token to verify incoming calls.

The webhook is the only link between Twilio and hermine.ai. Without it the phone rings, but the agent never answers.

Setup

Step 1: Copy your Twilio Auth Token

  1. Sign in to the Twilio Console.
  2. On the home page (Account Dashboard), the Account Info panel shows your Auth Token. It is hidden by default, click Show (or the eye icon) and copy the value.
  3. Is your Twilio number in a subaccount? Then switch into that exact subaccount (top right) and copy its Auth Token. The token must belong to the account that owns the number.

Security: The Auth Token is a password for your Twilio account. hermine.ai stores it encrypted and never shows it again in clear text. Do not share it.

Step 2: Store the number and token on the agent

  1. Open the agent under Agents → Edit and switch to the Audio & Voice tab.
  2. Make sure Audio features are enabled and pick the desired AI voice under Voice selection. The phone agent speaks with this voice too.
  3. In the Phone number field enter your Twilio number in international format, for example +498051958310. Drop the leading zero after the country code.
  4. Paste the token from step 1 into the Twilio Auth Token field.
  5. Click Save.

Tip: Use the number exactly as Twilio shows it in E.164 format (with + and country code, no spaces or dashes). hermine.ai matches the incoming call against this exact value. When editing later: leave the token field blank to keep the stored token.

Step 3: Configure the webhook in Twilio

  1. Sign in to the Twilio Console.
  2. Go to Phone Numbers → Manage → Active numbers and open your number.
  3. Switch to the Configure tab.
  4. In the Voice Configuration section:

    • Configure with: Webhook, TwiML Bin, Function, Studio Flow, Proxy Service

    • A call comes in: Webhook

    • URL: the webhook address of your hermine.ai instance, meaning the domain you log in at, plus /telephony/inbound:

      https://YOUR-HERMINE-DOMAIN/telephony/inbound

      Example: https://app.your-company.hermine.ai/telephony/inbound

    • HTTP: HTTP POST (not GET)

  5. You can leave Primary handler fails, Call status changes and Caller Name Lookup empty or on their defaults.
  6. Click Save configuration at the bottom.

Set the "A call comes in" webhook to the telephony inbound URL, HTTP POST

Step 4: Test call

Call the number from a phone. The agent should answer with the configured voice. After hanging up you will find the call as a phone conversation.

Viewing transcripts

Phone conversations appear under Conversations when the agent's Readable conversations toggle is on. You find the toggle in the Embed tab. If it is off, telephony still works, but the transcripts do not show up in the overview.

Privacy

During the call the audio is transmitted to our AI services for processing and the transcript is stored in the conversation history. Inform callers where needed, for example via an announcement or your privacy notice. Background on privacy and public operation: Public chatbot.

Troubleshooting

The call is rejected immediately (Twilio shows HTTP 403)

A 403 in the Twilio call log (tab Calls Log → Errors and Warnings) means hermine.ai could not verify the Twilio signature. Most common causes:

  • The Twilio Auth Token on the agent is empty, wrong, or belongs to a different Twilio account or subaccount than the number. Copy the token again from the account that owns the number (see step 1) and save it on the agent.
  • The webhook URL in Twilio does not point exactly to /telephony/inbound on your hermine.ai domain, or is set to GET instead of HTTP POST.

The phone rings but the agent does not answer

  • In Twilio, check that A call comes in is set to Webhook with HTTP POST and that the URL correctly points to /telephony/inbound on your domain.
  • Check that the phone number stored on the agent matches the Twilio number exactly, in E.164 format.

"This service is currently unavailable"

This message plays when the call is rejected, for example because voice is not active for the account, the monthly cost limit is reached, or the number cannot be matched to an agent. Check the account enablement and the stored number.

The "Phone number" and "Twilio Auth Token" fields are missing

  • You need administrator or superadmin rights.
  • Audio features must be enabled.
  • The voice/telephony beta must be enabled for your account.

Related: Email mailbox (IMAP) for another inbound channel, Public chatbot for web access.

Was this page helpful?