Bolna Voice AI & Exotel Integration Guide

1\ introduction this guide walks through integrating exotel phone numbers with bolna https //www bolna ai/ voice ai agents, using app bazaar call flows and the voicebot applet bolna is a voice ai platform for building phone agents, with a focus on indian languages and code switched speech once connected, calls run on your own exotel account, exophones, and balance what you'll achieve inbound calls to your exophone answered by a bolna agent, and outbound calls placed by bolna through your exotel account sequence of events a caller dials your exophone, or bolna places an outbound call through your exotel account exotel triggers the app you configured in app bazaar within the app, the voicebot applet points at a bolna endpoint, and a connect applet handles transfers to a human bolna runs the conversation and, when the agent transfers, returns the connect parameters to exotel the call is logged in both dashboards bolna stores an execution record with the transcript and call data two apps are needed, one for outbound and one for inbound, because each uses a different bolna endpoint set up the one you need, or both 2\ prerequisites requirement description exotel account an active account with api access and a dashboard login at my exotel com https //my exotel com/ exophone an exotel phone number to place and receive calls on exotel credentials api key, api token, account sid, and your account subdomain, for example api exotel com bolna account a bolna account https //platform bolna ai/ with at least one agent, and a bolna api key https //www bolna ai/docs/api reference/introduction 3\ create the exotel app for outbound calls 3 1 open app bazaar in your exotel dashboard, https //my exotel com/ go to app bazaar under the manage menu app bazaar in the exotel dashboard 3 2 create a new app select create and give the app a descriptive name, for example bolna outbound 3 3 add the voicebot applet drag the voicebot applet into the drop app here box this is the component that handles the ai voice interaction 3 4 configure the voicebot applet in the configuration popup set the url field to the bolna outbound endpoint https //api bolna ai/exotel callback enable record this if you want call recordings for quality assurance and compliance the outbound endpoint in the voicebot url field 3 5 add the connect applet for call transfers at the bottom of the voicebot popup there is a second drop app here section drag the connect applet into it, then find how do you want to control your connect params? select configure parameters dynamically by providing a url set the primary url to https //api bolna ai/exotel connect transfer this lets bolna supply the connect parameters when an agent transfers a live call where the call goes is decided on the bolna agent, not in this applet — see section 6 configuring the connect applet for transfers 3 6 save the app and note the app id select save exotel generates an app id for the app, shown next to it in app bazaar you will need this id when connecting your account to bolna saving the outbound app 4\ create the exotel app for inbound calls the inbound app follows the same shape, with a different voicebot url 4 1 create the app in app bazaar , select create and name the app, for example bolna inbound naming the inbound app 4 2 add and configure the voicebot applet drag the voicebot applet into the drop app here box, then set its url field to the bolna inbound endpoint https //api bolna ai/inbound call enable record this if you want recordings of inbound calls 4 3 add the connect applet for call transfers as with the outbound app, drag a connect applet into the second drop app here section, select configure parameters dynamically by providing a url , and set the primary url to https //api bolna ai/exotel connect transfer as with the outbound app, the transfer destination is configured on the bolna agent rather than in this applet — see section 6 configuring transfers on the inbound app 4 4 save the app and note the app id select save and note the generated app id 4 5 connect the exophone to the app map the exophone that should receive calls to the inbound app you just created mapping the exophone to the inbound app 5\ connect your exotel account to bolna with both app ids in hand, link the exotel account to bolna in the bolna dashboard https //platform bolna ai/ , open integrations under settings , filter by telephony , and select connect on the exotel card field value exotel api key your exotel api key exotel api token your exotel api token exotel account sid your exotel account sid exotel domain your exotel account domain, for example api exotel com exotel phone number the exophone you will use for calls exotel outbound app id the app id from section 3 exotel inbound app id the app id from section 4 select connect exotel to save bolna validates the credentials and establishes the link from that point, bolna's calls use your exotel infrastructure, numbers, and balance see connect your exotel account https //www bolna ai/docs/exotel/connect provider for this flow in bolna's own docs 6\ configure call transfers in bolna the connect applet you added in sections 3 5 and 4 3 is the mechanism for handing a live call to a human the routing decision itself lives on the bolna agent when the agent decides to transfer, exotel requests the connect parameters from https //api bolna ai/exotel connect transfer , and bolna responds with the destination configured on the agent's transfer call tool without the connect applet in the flow, exotel has nowhere to route the call and the transfer fails configure the tool in the agent's tools tab in bolna setting purpose description (prompt) tells the model when to trigger a transfer, for example "transfer when the caller asks for sales, pricing, or demos" transfer destination the phone number to dial, in international format pre tool message what the agent says while transferring, with support for multiple languages pre call webhook optional notifies a url of your choice before the transfer, carrying the transfer reason and a conversation summary for multiple departments, add a separate transfer function for each, with its own number and trigger description the agent chooses between them from the conversation, so there is no menu or decision tree to configure in the exotel flow refer to transfer live calls https //www bolna ai/docs/tool calling/transfer calls for the full configuration 7\ make outbound calls 7 1 from the bolna dashboard open your agent, select exotel as the call provider, then enter a recipient number in e 164 format and place the call choosing exotel as the agent's call provider placing a call through exotel your own exophones are available as the caller id only after the exotel account is connected 7 2 using the api set exotel as the agent's input and output provider, then trigger the call "tools config" { "output" { "format" "wav", "provider" "exotel" }, "input" { "format" "wav", "provider" "exotel" } } refer to bolna's v2 agent apis https //www bolna ai/docs/api reference/agent/v2/overview for creating and updating agents the older /agent endpoint is deprecated place the call with agent id and recipient phone number in e 164 format refer to make a call https //www bolna ai/docs/api reference/calls/make for all parameters curl x post "https //api bolna ai/call" \ h "authorization bearer $bolna api key" \ h 'content type application/json' \ d '{ "agent id" "fd3d9b56 0742 4a39 aaac 50dec1f37d00", "recipient phone number" "+919876543210" }' the response returns an execution id { "message" "done", "status" "queued", "execution id" "b7140255 af33 4608 8e97 04dd944b8e48" } 7 3 check the result of the call retrieve the execution with get /executions/{execution id} to get the transcript, cost, and telephony data refer to retrieve an execution https //www bolna ai/docs/api reference/executions/get execution a normal call moves through these statuses scheduled → queued → initiated → ringing → in progress → call disconnected → completed completed is final and can arrive two to three minutes after the call disconnects, once recordings and data extraction finish unanswered and failed calls end in statuses such as busy , no answer, failed, or balance low see call statuses https //www bolna ai/docs/post call/list phone call status for the full list 7 4 batch calling to run campaigns across many numbers with the same agent, use bolna's batch apis the exotel configuration is unchanged 8\ receive inbound calls once the exophone is mapped to the inbound app, assign a bolna agent to that number from the bolna dashboard select assign inbound agent , choose the phone number, choose the agent, and confirm using the api \# list the phone numbers on the account curl x get "https //api bolna ai/phone numbers/all" \\ h "authorization bearer $bolna api key" \# assign an agent to the number curl x post "https //api bolna ai/inbound/setup" \\ h "authorization bearer $bolna api key" \\ h 'content type application/json' \\ d '{ "agent id" "3c90c3cc 0d44 4b50 8888 8dd25736052a", "phone number id" "123e4567 e89b 12d3 a456 426614174000" }' refer to list phone numbers https //www bolna ai/docs/api reference/phone numbers/get all and set inbound agent https //www bolna ai/docs/api reference/inbound/agent for all parameters to unlink an agent later, call post /inbound/unlink — see remove inbound agent https //www bolna ai/docs/api reference/inbound/unlink call the exophone to test exotel routes the call to the inbound app, the voicebot applet hands it to bolna, and the assigned agent answers 9\ troubleshooting issue solution calls fail with an authentication error confirm the api key, api token, account sid, and domain saved in bolna match your exotel account, with no leading or trailing whitespace outbound calls do not connect confirm exotel outbound app id matches the app id of the app whose voicebot url is https //api bolna ai/exotel callback the inbound and outbound app ids are not interchangeable inbound calls are not answered confirm the exophone is mapped to the inbound app, that the voicebot url is https //api bolna ai/inbound call , and that an agent is assigned to the number in bolna call transfers to a human fail confirm a connect applet sits inside the voicebot applet with its primary url set to https //api bolna ai/exotel connect transfer and dynamic parameters selected, and that the agent has a transfer call tool with a destination number configured in bolna call ends immediately after connecting check the bolna account balance calls that cannot be funded end with the balance low status call status never reaches completed post call processing can take two to three minutes retrieve the execution again before treating the call as failed test each app with a call before running production campaigns related voicebot applet https //docs exotel com/exotel agentstream/voicebot applet — configuring bidirectional streams connect applet for agent handover https //docs exotel com/exotel agentstream/connect applet for agent handover — routing a live call to a human recording options in the voicebot applet https //docs exotel com/exotel agentstream/recording options in the voicebot applet — the record setting used above agentstream applets https //docs exotel com/exotel agentstream/agentstream applets — the full applet reference connect exotel sip trunking to bolna voice ai https //docs exotel com/exotel agentstream/connect exotel sip trunking to bolna voice ai — the sip trunking route to bolna bolna exotel docs https //www bolna ai/docs/exotel — bolna's own exotel configuration reference