​
Making an Observe Request

Send a POST request to https://new-prod.vocera.ai/observability/v1/observe/ with the following specification:

​
Headers

  • X-VOCERA-API-KEY: Your API key copied from above

​
Request Body

  • call_id (required): Unique identifier for the call

  • Either agent or assistant_id (required):

    • agent: The agent ID as shown on your dashboard

    • assistant_id: The assistant ID associated with agent

  • Either voice_recording or voice_recording_url (required):

    • voice_recording: Audio file of the call recording

    • voice_recording_url: URL to the call recording audio file

  • call_ended_reason (optional): Reason for call termination

  • customer_number (optional): Phone number of the customer

  • transcript_type (required): Format the transcript is sent in. can be vocera, vapi, retell or deepgram

  • transcript_json (required): JSON object containing the transcript of the call. Can be in Vocera, Vapi or Retell format

  • metadata (optional): Dictionary with additional data

  • dynamic_variables (optional): Dictionary of dynamic variables and values. These values will replace variables in double curly braces in the agent description.

​
Example Request

{
    "call_id": "call_20240317_123456",
    "agent": 1,
    "voice_recording_url": "https://storage.example.com/calls/recording_123.wav",
    "call_ended_reason": "completed",
    "customer_number": "+1234567890",
    "transcript_type": "vocera",
    "transcript_json": [
        {
            "role": "Testing Agent",
            "content": "Hello, how can I help you today?",
            "end_time": 1.94,
            "start_time": 1.44
        },
        {
            "role": "Main Agent",
            "content": "Hi, I need help with my account.",
            "end_time": 7.54,
            "start_time": 3.1
        }
    ],
    "metadata": {
        "customer_id": "cust_456",
        "department": "support",
        "priority": "high"
    },
    "dynamic_variables": {
        "customer_name": "John Smith",
        "account_type": "premium",
        "last_interaction": "2024-03-10"
    }
}

Transcript JSON Example:

Vocera Format

[
   {
      "role": "Testing Agent",
      "content": "Hello.",
      "end_time": 1.9399999,
      "start_time": 1.4399999
   },
   {
      "role": "Main Agent",
      "content": "Hello. I want to book appointment today. My name is John.",
      "end_time": 7.539999511718751,
      "start_time": 3.1
   },
   {
      "role": "Testing Agent",
      "content": "Well, I mean, sure. What time exactly are we talking about here",
      "end_time": 15.71,
      "start_time": 12.01
   },
   {
      "role": "Main Agent",
      "content": "6 PM.",
      "end_time": 18.269999,
      "start_time": 17.609999
   },
   {
      "role": "Testing Agent",
      "content": "Great. I'll book that for you. Just a sec.",
      "end_time": 21.45,
      "start_time": 19.16
   },
   {
      "role": "Main Agent",
      "content": "Okay.",
      "end_time": 23.25,
      "start_time": 22.75
   },
   {
      "data": {
         "id": "call_5otWH44dxeXEHY8RlhYYaFbV",
         "name": "bookUserAppointment",
         "arguments": "{\"name\": \"John\", \"datetime\": \"2024-10-17T18:00:00\"}"
      },
      "role": "Function Call",
      "content": "",
      "end_time": 23.164,
      "start_time": 23.164
   },
   {
      "data": {
         "id": "call_5otWH44dxeXEHY8RlhYYaFbV",
         "name": "bookUserAppointment",
         "result": "No result returned."
      },
      "role": "Function Call Result",
      "end_time": 24.6,
      "start_time": 24.6
   },
   {
      "role": "Testing Agent",
      "content": "1 moment.",
      "end_time": 25.92,
      "start_time": 25.1
   },
   {
      "role": "Main Agent",
      "content": "Yes. Yes.",
      "end_time": 27.979999999999997,
      "start_time": 27.08
   },
   {
      "role": "Testing Agent",
      "content": "Appointment booked for 6 PM today.",
      "end_time": 29.5,
      "start_time": 27.08
   },
   {
      "role": "Main Agent",
      "content": "Oh, okay. Bye.",
      "end_time": 31.72,
      "start_time": 30.64
   },
   {
      "role": "Testing Agent",
      "content": "Bye.",
      "end_time": 33.6,
      "start_time": 33.1
   }
]

​
Method 1: Using a Voice Recording URL

Send a voice recording URL to be processed by our API.

​
Request Body

  • call_id (required): Unique identifier for the call

  • agent (required): The agent ID as shown on your dashboard

  • voice_recording_url (required): URL to the call recording audio file

  • call_ended_reason (optional): Reason for call termination

  • customer_number (optional): Phone number of the customer

  • transcript_json (required): JSON object containing the transcript of the call. Can be in Vocera, Vapi or Retell format

  • metadata (optional): Dictionary with additional data

  • dynamic_variables (optional): Dictionary of dynamic variables and values. These values will replace variables in double curly braces in the agent description.

curl -X POST https://new-prod.vocera.ai/observability/v1/observe/ \
  -H "X-VOCERA-API-KEY: your_api_key" \
  -F "call_id=unique_call_id" \
  -F "agent=your_agent_id" \
  -F "voice_recording_url=https://example.com/path/to/audio_file.wav" \
  -F "call_ended_reason=optional_reason" \
  -F "customer_number=optional_customer_number" \
  -F "transcript_json=[]" \
  -F "metadata={}" \
  -F "dynamic_variables={}"

​
Method 2: Using a Voice Recording File

Upload an audio file directly in the request.

​
Request Body

  • call_id (required): Unique identifier for the call

  • agent (required): The agent ID as shown on your dashboard

  • voice_recording (required): Audio file of the call recording

  • call_ended_reason (optional): Reason for call termination

  • customer_number (optional): Phone number of the customer

  • transcript_json (required): JSON object containing the transcript of the call. Can be in Vocera, Vapi or Retell format

  • metadata (optional): Dictionary with additional data

  • dynamic_variables (optional): Dictionary of dynamic variables and values. These values will replace variables in double curly braces in the agent description.

curl -X POST https://new-prod.vocera.ai/observability/v1/observe/ \
  -H "X-VOCERA-API-KEY: your_api_key" \
  -F "call_id=unique_call_id" \
  -F "agent=your_agent_id" \
  -F "voice_recording=@/path/to/audio_file.wav" \
  -F "call_ended_reason=optional_reason" \
  -F "customer_number=optional_customer_number" \
  -F "transcript_json=[]" \
  -F "metadata={}" \
  -F "dynamic_variables={}"