Bring another person onto a call

Sometimes one call needs a third person: a pharmacist who can answer a question about a prescription, or a colleague the caller asks for. A Call Agent can add that person to the call while the call runs. This is also how you forward a call with Resia: to a colleague, a front desk, or any other number. In this guide, you will tell the agent whom it may add and when. Then you will place a test call in which the agent adds a second person, and read both conversations.

How it works

A call with an added person has three parties: the agent, the primary participant, and an additional participant. The primary participant is the person the call is with. The additional participant is the person the agent adds. The agent adds the person the way a receptionist does. It tells the caller to hold, dials the second person, speaks with them in private, asks whether they can join, and then connects everyone. The agent stays on the call, so the call keeps one transcript, one recording, and one analysis. From then on, it speaks only when someone asks it something.

You describe the people once, on the agent, not on each call:

• primary_participant names the person the call is with, such as patient. The transcript and the instructions use that name.
• additional_participants names each person the agent may add, such as pharmacy. Three settings describe how that person joins:
  • dial says when Resia calls them. on_agent_request means the agent decides during the conversation. at_start means Resia calls them as soon as the call starts.
  • intro says how they join. private_first means the agent speaks with them in private first, while the caller waits on hold. direct means they join the open conversation at once.
  • phone_number is optional. Set it when the person is always the same, such as a front desk. Leave it out when each call names the number.

Today, Resia supports one additional participant per call, dialed on_agent_request with intro set to private_first. That is the receptionist pattern above. You can save other settings on an agent, but a call that uses them is refused with 422, and the message names the limit.

Before you start

• Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
• An approved, active Call Agent. The Quickstart creates one.
• Two phones you control: one for the person the agent calls, one for the person the agent adds. A test call is a real call to both. Normal call charges apply.

Name the people on the agent

Send a complete update, as in Change what an agent says. The example names the person on the call patient, allows one additional participant called pharmacy, and tells the agent when to add them.

read -r -p 'Call Agent id: ' CALL_AGENT_ID

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --output agent-current.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/openapi.json" --output resia-openapi.json

jq --slurpfile api resia-openapi.json \
  'with_entries(select(.key as $key | $api[0].components.schemas.CallAgentWrite.properties | has($key)))
   | .primary_participant = "patient"
   | .additional_participants = {pharmacy: {dial: "on_agent_request", intro: "private_first", phone_number: null}}
   | .instructions = (.instructions + " When the patient asks about a prescription, bring the pharmacy onto the call and introduce them.")' \
  agent-current.json > agent-update.json

curl --fail-with-body --silent --show-error \
  --request PUT "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @agent-update.json \
  | jq '{id, primary_participant, additional_participants, review_status}'

Expected result: HTTP 200. The answer shows primary_participant and additional_participants. Resia may review the new instructions before they take effect. Continue when review_status is approved.

In the portal: open the agent's Settings tab. Fill in Primary participant, select Add participant, and set the Participant name, Dial mode, Intro mode, and an optional Phone number. Edit the instructions on the Behavior tab.

API reference: Replace a Call Agent describes primary_participant and additional_participants with their settings.

Place the call

Name the second person's phone number in additional_participants, under the same name as on the agent. A person with a fixed phone_number on the agent needs no entry.

read -r -p 'The patient phone number, including + and country code: ' TO_PHONE_NUMBER
read -r -p 'The pharmacy phone number, including + and country code: ' PHARMACY_PHONE_NUMBER
CALL_REQUEST_KEY=$(uuidgen)

jq -n --arg agent "$CALL_AGENT_ID" --arg patient "$TO_PHONE_NUMBER" --arg pharmacy "$PHARMACY_PHONE_NUMBER" \
  '{call_agent_id: $agent, to_phone_number: $patient, inputs: {}, additional_participants: {pharmacy: $pharmacy}}' > multi-party-call.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/calls" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CALL_REQUEST_KEY" \
  --data-binary @multi-party-call.json \
  --output multi-party-call-response.json

jq '{id, status}' multi-party-call-response.json

Expected result: HTTP 202. When the patient asks about the prescription, the agent tells them to hold, dials the pharmacy, speaks with the pharmacist in private, and then connects everyone. If nobody answers at the pharmacy, the agent returns to the patient and explains.

A call batch cannot add people. Place these calls with POST /v1/calls.

In the portal: open the agent and select Test call. The dialog asks for one number per participant.

API reference: Place a call describes additional_participants on a call.

Read both conversations

CALL_ID=$(jq -er '.id' multi-party-call-response.json)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/calls/$CALL_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '{status, additional_participants, transcript, additional_transcripts}'

Expected result: transcript holds the open conversation: every turn the patient could hear. additional_transcripts holds the agent's private conversation with the pharmacist, under the name pharmacy. Every turn has a started_at from one clock, so you can put the two lists in time order. additional_participants shows when the pharmacy joined and left.

In the portal: open History → Calls and select the call. The private conversation has its own tab beside the open conversation.

API reference: Read a call.

Inbound calls

An inbound call has no request that can carry a phone number. Give every additional participant on an inbound agent a fixed phone_number. If one has no number, Resia does not answer the call, and it rings out.

If something fails

• 422 when you save the agent: primary_participant without additional_participants, or the reverse.
• 422 when you place the call, because the request names a person who is not on the agent.
• 422 when you place the call, because a person has no number on the agent and none in the request.
• 422 when you place the call, because the agent uses a dial or intro setting that Resia does not support yet.
• 422 for a call of a speech_to_speech Call Agent: those agents cannot add people.
• The agent never adds the person: its instructions do not say when to do it. Write the condition and use the person's name.
• The agent says the person could not be reached: nobody answered, or the line reached voicemail or a phone menu that the agent could not get through. The agent returns to the caller and offers to try again.

Next steps

• Get results after a call: transcript, analysis, and recording of the call.
• Receive an inbound call: an inbound agent with a fixed participant number.
• Call Agents: the field tables for participants.