From c74029577ba9b3f99e826805feeb9b4c5ecaafa5 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 18 Aug 2025 20:06:16 +0000
Subject: [PATCH] Update event schemas with additional metadata and formatting
 details

Co-authored-by: sahil <sahil@vapi.ai>
---
 fern/server-url/events.mdx | 42 ++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/fern/server-url/events.mdx b/fern/server-url/events.mdx
index 0df0ce2ed..98761bdfb 100644
--- a/fern/server-url/events.mdx
+++ b/fern/server-url/events.mdx
@@ -16,6 +16,11 @@ All messages sent to your Server URL are `POST` requests with this body shape:
 }
 ```
 
+Common metadata included on most events:
+- `phoneNumber`, `timestamp`
+- `artifact` (recording, transcript, messages, etc.)
+- `assistant`, `customer`, `call`, `chat`
+
 Most events are informational and do not require a response. Responses are only expected for these types sent to your Server URL:
 - "assistant-request"
 - "tool-calls"
@@ -168,13 +173,14 @@ Or return an error message to be spoken to the caller:
     "type": "end-of-call-report",
     "endedReason": "hangup",
     "call": { /* Call Object */ },
-    "recordingUrl": "https://.../recordings/1234.wav",
-    "summary": "The user asked about the weather...",
-    "transcript": "AI: How can I help? User: What's the weather? ...",
-    "messages": [
-      { "role": "assistant", "message": "How can I help?" },
-      { "role": "user", "message": "What's the weather?" }
-    ]
+    "artifact": {
+      "recording": { /* Recording object with URLs */ },
+      "transcript": "AI: How can I help? User: What's the weather? ...",
+      "messages": [
+        { "role": "assistant", "message": "How can I help?" },
+        { "role": "user", "message": "What's the weather?" }
+      ]
+    }
   }
 }
 ```
@@ -200,7 +206,8 @@ Sent when an update is committed to the conversation history.
 {
   "message": {
     "type": "conversation-update",
-    "messages": [ /* current conversation messages */ ]
+    "messages": [ /* current conversation messages */ ],
+    "messagesOpenAIFormatted": [ /* openai-formatted messages */ ]
   }
 }
 ```
@@ -216,7 +223,9 @@ Partial and final transcripts from the transcriber.
     "role": "user",
     "transcriptType": "partial",
     "transcript": "I'd like to book...",
-    "isFiltered": false
+    "isFiltered": false,
+    "detectedThreats": [],
+    "originalTranscript": "I'd like to book..."
   }
 }
 ```
@@ -301,7 +310,8 @@ Sent when the transcriber switches based on detected language.
 ```json
 {
   "message": {
-    "type": "language-change-detected"
+    "type": "language-change-detected",
+    "language": "es"
   }
 }
 ```
@@ -320,6 +330,15 @@ When requested in `assistant.serverMessages`, hangup and forwarding are delegate
 }
 ```
 
+```json
+{
+  "message": {
+    "type": "phone-call-control",
+    "request": "hang-up"
+  }
+}
+```
+
 ### Knowledge Base Request (Custom)
 
 If using `assistant.knowledgeBase.provider = "custom-knowledge-base"`.
@@ -328,7 +347,8 @@ If using `assistant.knowledgeBase.provider = "custom-knowledge-base"`.
 {
   "message": {
     "type": "knowledge-base-request",
-    "messages": [ /* conversation so far */ ]
+    "messages": [ /* conversation so far */ ],
+    "messagesOpenAIFormatted": [ /* openai-formatted messages */ ]
   }
 }
 ```