Skip to content

Commit

Permalink
Docs to explain how outbound calls work (livekit#145)
Browse files Browse the repository at this point in the history
  • Loading branch information
shahafabileah authored May 24, 2023
1 parent d302a44 commit 5315642
Showing 1 changed file with 46 additions and 0 deletions.
46 changes: 46 additions & 0 deletions docs/telephony.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,8 @@ The `OutboundCall` class provides a simple abstraction for creating outbound cal

### Example: Making an outbound call

Prior to running this script to initiate an outbound call, you still need the `TelephonyServer` from above to be running.

```python
import os
from vocode.streaming.telephony.hosted.outbound_call import OutboundCall
Expand Down Expand Up @@ -263,6 +265,50 @@ if __name__ == '__main__':
call.end()
```

### How outbound calls work

Here's what happens under the hood for an outbound call.

The `OutboundCall` calls Twilio to initiate the call, giving it a URL to call after the call is initiated:
```
twilio_call = self.twilio_client.calls.create(
url=f"https://{self.base_url}/twiml/initiate_call/{self.conversation_id}",
```

In your main.py you create and start a `TelephonyServer`. The TelephonyServer itself includes a couple of routers:
* `TwiMLRouter`
* `CallsRouter`

`TwiMLRouter` includes the matching route:
```
self.router.add_api_route(
"/twiml/initiate_call/{id}", self.call_twiml, methods=["POST"]
)
```

This route returns the template `connect_call.xml` which uses TwiML to tell Twilio to establish a websocket with a given URL:
```
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Connect>
<Stream url="wss://{{ base_url }}/connect_call/{{ id }}" />
</Connect>
</Response>
```

CallsRouter includes that second route:
```
self.router.websocket("/connect_call/{id}")(self.connect_call)
```

This is where we get the websocket connection. We then create the `Call` object and start it:
```
await call.attach_ws_and_start(websocket)
```

The `Call` is a kind of `StreamingConversation` that manages the various pieces: transcriber, synthesizer, agent, etc.


## Inbound Calls

The `InboundCallServer` class provides a simple abstraction to create an endpoint that can host your agent
Expand Down

0 comments on commit 5315642

Please sign in to comment.