Phonic
Stream meeting audio to your Phonic agent and play its responses back into the meeting.
Recall.ai connects to Phonic's speech-to-speech WebSocket API. Use a saved Phonic agent or configure one for each meeting. Phonic runs the conversation and your server tools while Recall.ai handles meeting audio, playback, and interruptions.
Setup
1. Prepare your Phonic agent
Follow Phonic's agent setup guide to create an agent. Configure its instructions, voice, and tools, and note its agent name and project name. You can also use an existing agent.
Create a Phonic API key with access to that project. You can also supply inline settings without creating a saved agent, as shown below.
2. Add your credentials to Recall.ai
Open Agents → Phonic in the Recall region where you create bots:
Select the workspace used by your Recall API key, then save your Phonic key. Recall.ai reads the key from that workspace's saved credentials when connecting. Changes apply to new connections.
Quickstart
Call Create Bot with your meeting URL and Phonic agent name. Replace meeting-assistant with your agent's name and main with its project name.
We recommend setting the relevant meeting platform in variant to web_4_core when pairing this audio agent with a video provider or a kind: "webpage" source. See bot sizing guidance.
{
"meeting_url": "MEETING_URL",
"output_media": {
"audio": {
"kind": "phonic",
"config": {
"agent": "meeting-assistant",
"project": "main"
}
}
}
}Once the bot joins, Recall.ai starts a Phonic conversation, sends the meeting audio mix, and plays the agent's replies. When Phonic accepts a participant's interruption, Recall.ai clears queued agent audio so the interrupted reply stops playing.
For recording the agent's voice, see Recording meeting agents. For response controls, see the Meeting agents FAQ.
Additional configurations
The output_media.audio.config object accepts fields from Phonic's native config message. Supply the settings directly; Recall.ai adds type: "config" and manages the audio transport. The serialized configuration must be at most 1 MiB.
Common configuration fields include:
| Field | Required | Description |
|---|---|---|
agent | For a saved agent | Name of the saved agent to use; see Phonic's conversation configuration schema. Must be nonempty and at most 256 UTF-8 bytes. Omit it to use inline settings. |
project | No | Phonic project name, as described in the configuration schema. Defaults to main. Must be nonempty and at most 256 UTF-8 bytes. |
template_variables | No | An object of string values for Phonic's template variables. Recall.ai adds the reserved bot variables described below. |
system_prompt | No | Conversation instructions, using the native configuration schema. See Phonic's prompting guide for writing instructions. Can contain template variables. |
welcome_message | No | Opening message from the configuration schema. Set generate_welcome_message to false to use this message when the saved agent otherwise generates its greeting. |
generate_welcome_message | No | Whether Phonic generates the opening message. Set to false to use welcome_message. See the configuration schema. |
voice_id | No | Voice to use for this conversation. See Phonic's voices guide. |
tools | No | Phonic tool selection, such as an array of saved webhook tool names. See the tools guide and configuration schema. Client-side WebSocket tools are not executed by Recall.ai. |
mcp_servers | No | Names of MCP servers connected to Phonic. See MCP tools. Phonic calls these servers directly. |
configuration_endpoint | No | An agent configuration endpoint that Phonic calls for settings when the conversation starts. See the template-variable precedence note below. |
no_input_end_conversation_sec | No | Inactivity limit in seconds: an integer from 30 to 3600. Recall.ai sends 3600 when omitted. See the configuration schema. |
max_conversation_duration_sec | No | Maximum conversation length in seconds: an integer from 1 to 7200. When omitted, Phonic's agent or service default applies. See the configuration schema. |
detect_voicemail_tone | No | Whether Phonic detects voicemail tones. Recall.ai sends false when omitted. See the configuration schema. |
Phonic settings supplied for a conversation override the corresponding saved agent settings. Recall.ai also supplies the project, no_input_end_conversation_sec, and detect_voicemail_tone defaults above when you omit them.
The API key comes from saved workspace credentials. api_key, credential_id, type, and a top-level url are not accepted in this config. A nested configuration_endpoint.url is supported.
Keep Phonic's input_modality and output_modality set to speech; see the agent settings reference.
Personalize a saved agent
Use this config to provide a meeting topic and customize the greeting:
{
"agent": "meeting-assistant",
"project": "main",
"template_variables": {
"meeting_topic": "Product planning"
},
"generate_welcome_message": false,
"welcome_message": "Hi, I'm here to help with {{meeting_topic}}."
}You can also use {{meeting_topic}} in the agent's system prompt. Values in template_variables must be strings. Supply values for every variable that your agent requires and does not give a default value. See Phonic's template variable guide for declaring variables and setting defaults.
Use inline settings
Omit agent to define the conversation directly:
{
"project": "main",
"system_prompt": "You are a helpful meeting assistant. Keep spoken replies brief.",
"voice_id": "sabrina",
"generate_welcome_message": false,
"welcome_message": "Hi, how can I help with the meeting?"
}You can include other settings from Phonic's config schema, subject to the transport restrictions above. Phonic validates provider-specific settings when the conversation starts.
Load settings from your server
Configure configuration_endpoint on your saved Phonic agent or in the bot's config to have Phonic fetch conversation settings from your server. Follow Phonic's configuration endpoint guide for the request and response schemas.
Phonic includes the conversation's template_variables in the request to your endpoint, including the recall_bot_id and recall_api_base_url values described below. Your server can use these to look up meeting-specific settings.
Recall.ai always supplies template_variables, including bot context. Phonic gives that object precedence over template_variables returned by the configuration endpoint; it does not merge the two. Put per-meeting variable values in the bot's config.template_variables.
Settings sent in the conversation's config take precedence over the endpoint's response, which takes precedence over the saved agent's settings. This includes the inactivity and voicemail-detection defaults that Recall.ai sends when you omit them.
Use Recall bot context in tools
Recall.ai automatically supplies these values in template_variables when starting the conversation:
| Variable | Value |
|---|---|
recall_bot_id | The Recall bot's ID, matching the ID returned by Create Bot. |
recall_api_base_url | The bot's regional Recall API base URL, without an API version path, such as https://us-west-2.recall.ai. |
These names are reserved: Recall.ai replaces any values you supply for them and preserves your other variables. You do not need to add them to the bot request.
To pass the values to your tool server, configure these endpoint_headers on a Phonic webhook tool:
{
"endpoint_headers": {
"X-Recall-Bot-Id": "{{recall_bot_id}}",
"X-Recall-Api-Base-Url": "{{recall_api_base_url}}"
}
}This is part of the tool's configuration in Phonic. Phonic substitutes the values before calling your server. Template variables are not substituted in tool URLs, request bodies, or MCP tool settings; see Phonic's template variable guide.
Your server can use the bot ID and base URL to send chat messages, start a screenshare, or make the bot leave. Append the endpoint's versioned path to the base URL. Your server still needs your Recall API key to authenticate those requests; the variables contain no Recall credentials.
For example tools, see Add meeting tools.
Add a camera or avatar
Phonic is supported under output_media.audio. You can combine it with an independent camera or screenshare source. When audio is configured, the meeting audio mix goes only to the audio agent; camera and screenshare sources do not receive it.
To use an automatic avatar, combine output_media.audio with automatic_video_output, leaving output_media.camera and output_media.screenshare absent.
FAQ
Where should I implement tool calls?
Use Phonic webhook tools or connected MCP servers for your application logic. Follow the tools guide to attach them to your agent. Recall.ai does not execute client-side WebSocket tools: it returns an unsupported-tool result and emits a customer-visible warning while the conversation continues.
Updated 20 minutes ago
