From 5315642e5c5a82ada634f130d128db39c5b7d21a Mon Sep 17 00:00:00 2001
From: shahafabileah <shahaf@gmail.com>
Date: Wed, 24 May 2023 16:27:16 -0700
Subject: [PATCH] Docs to explain how outbound calls work (#145)

Adapted from this discussion:
https://discord.com/channels/1079125925163180093/1110708807883034646/1110708812979118183
---
 docs/telephony.mdx | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/telephony.mdx b/docs/telephony.mdx
index fd69cd276..16397712a 100644
--- a/docs/telephony.mdx
+++ b/docs/telephony.mdx
@@ -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
@@ -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