Webhook Reference

StarAgent sends a POST request to your webhook URL for every missed call and voicemail. The body is always JSON.

Events

incoming_callSent immediately when a call arrives

Fires the moment your monitored number receives a call. Contains caller identity and location data from the carrier.

voicemailSent after the voicemail is transcribed

Fires after the caller leaves a message and transcription completes. Contains the full transcription (or extracted data), a link to the audio recording, and all caller metadata.

Request format

Every webhook is a POST with the header Content-Type: application/json. Your endpoint should return a 2xx status. StarAgent does not currently retry on failure.

`incoming_call` payload

{
  "event": "incoming_call",
  "call_id": "clxyz1234567890abcdef",
  "call_sid": "CA1234567890abcdef1234567890abcd",
  "timestamp": "2026-02-21T18:30:00.000Z",
  "business_name": "Sunrise Dental",
  "business_phone": "+15551234567",
  "caller": {
    "phone": "+15559876543",
    "name": "Jane Smith",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "forwarded_from": "+15551111111",
  "direction": "inbound"
}

Field	Type	Description
event	string	Always "incoming_call"
call_id	string	Unique StarAgent call identifier
call_sid	string	Twilio Call SID for cross-referencing
timestamp	string	ISO 8601 timestamp of when the call arrived
business_name	string	Your business name as configured in StarAgent
business_phone	string	Your monitored phone number (E.164 format)
caller.phone	string	Caller's phone number (E.164 format)
caller.name	string?	Caller ID name from the carrier, if available
caller.city	string?	Caller's city from the carrier
caller.state	string?	Caller's state or region
caller.country	string?	Caller's two-letter country code
forwarded_from	string?	The number that forwarded this call, if applicable
direction	string?	Call direction, typically "inbound"

`voicemail` payload

Includes all fields from incoming_call plus a voicemail object.

{
  "event": "voicemail",
  "call_id": "clxyz1234567890abcdef",
  "call_sid": "CA1234567890abcdef1234567890abcd",
  "timestamp": "2026-02-21T18:31:15.000Z",
  "business_name": "Sunrise Dental",
  "business_phone": "+15551234567",
  "caller": {
    "phone": "+15559876543",
    "name": "Jane Smith",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "voicemail": {
    "transcription": "Hi, this is Jane. I was calling about rescheduling my cleaning appointment next Tuesday. Could you call me back? Thanks.",
    "recording_url": "https://staragent.io/api/recordings/clxyz1234567890abcdef?token=a1b2c3d4e5f6...",
    "recording_duration": 12,
    "recording_sid": "RE1234567890abcdef1234567890abcd",
    "voicemail_mode": "transcribe"
  },
  "forwarded_from": "+15551111111",
  "direction": "inbound"
}

voicemail fields

Field	Type	Description
voicemail.transcription	string	Full transcription or extracted data, depending on your voicemail mode
voicemail.recording_url	string	Direct link to the voicemail audio (.wav). Token-authenticated, valid indefinitely.
voicemail.recording_duration	number?	Duration of the voicemail in seconds
voicemail.recording_sid	string?	Twilio Recording SID for cross-referencing
voicemail.voicemail_mode	string	The mode used to process this voicemail. One of "transcribe", "extract", or "prompt".
extracted_fields	object?	Present on voicemail events when the transcription contains Label-style lines. Keys are lowercased labels, values are the caller's answers. Omitted when empty.
inferred_contact	object?	Best-effort name, email, and phone from transcript analysis plus extracted lines. Fields may be null. Omitted when all values are null.

Structured fields on voicemail webhooks

For integrations and OpenClaw-style automations, StarAgent also sends extracted_fields and inferred_contact when it can derive them, so downstream tools do not need to re-parse the transcription.

{
  "event": "voicemail",
  "call_id": "clxyz1234567890abcdef",
  "call_sid": "CA1234567890abcdef1234567890abcd",
  "timestamp": "2026-02-21T18:31:15.000Z",
  "business_name": "Sunrise Dental",
  "business_phone": "+15551234567",
  "caller": {
    "phone": "+15559876543",
    "name": "Jane Smith",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "voicemail": {
    "transcription": "Name: Jane Smith\nPhone: 555-987-6543\nReason: Boarding inquiry",
    "recording_url": "https://staragent.io/api/recordings/clxyz1234567890abcdef?token=a1b2c3d4e5f6...",
    "recording_duration": 18,
    "recording_sid": "RE1234567890abcdef1234567890abcd",
    "voicemail_mode": "extract"
  },
  "extracted_fields": {
    "name": "Jane Smith",
    "phone": "555-987-6543",
    "reason": "Boarding inquiry"
  },
  "inferred_contact": {
    "name": "Jane Smith",
    "email": null,
    "phone": "555-987-6543"
  },
  "forwarded_from": null,
  "direction": "inbound"
}

Voicemail modes and transcription output

The content of voicemail.transcription depends on which voicemail mode you configured in Setup.

transcribe

Plain-text transcription of the voicemail, word for word.

extract

Structured extraction using your template. The transcription field contains the filled-in template fields (e.g. Name, Phone, Reason, Urgency). This is ideal for feeding directly into a CRM or form.

prompt

Custom prompt applied to the audio. The transcription field contains whatever your prompt instructs the model to return, such as a summary, sentiment analysis, or action items.

Example with extract mode

If your template is "Name / Phone / Reason / Preferred time / Urgency", the transcription field in the webhook will look like this.

{
  "event": "voicemail",
  "call_id": "clxyz1234567890abcdef",
  "call_sid": "CA1234567890abcdef1234567890abcd",
  "timestamp": "2026-02-21T18:31:15.000Z",
  "business_name": "Sunrise Dental",
  "business_phone": "+15551234567",
  "caller": {
    "phone": "+15559876543",
    "name": "Jane Smith",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "voicemail": {
    "transcription": "Name: Jane Smith\nPhone: 555-987-6543\nReason: Reschedule cleaning\nPreferred time: Tuesday morning\nUrgency: Not urgent",
    "recording_url": "https://staragent.io/api/recordings/clxyz1234567890abcdef?token=a1b2c3d4e5f6...",
    "recording_duration": 18,
    "recording_sid": "RE1234567890abcdef1234567890abcd",
    "voicemail_mode": "extract"
  },
  "forwarded_from": null,
  "direction": "inbound"
}

Recording URL

The voicemail.recording_url is a signed URL that serves the audio file without requiring login. You can use it to play the recording in your app, attach it to a support ticket, or store it in your own system. The URL does not expire, but it is unique per call and cannot be guessed.

Fetching the audio. Send a GET request to the URL. The response is audio/wav with standard HTTP caching headers.

Tips for integration builders

Use the event field to route payloads. You may receive incoming_call first, followed by voicemail seconds later for the same call. Match on call_id to correlate them.
Nullable fields like caller.name may be null if the carrier does not provide caller ID data. Always handle nulls gracefully.
Phone numbers use E.164 format (e.g. +15551234567). Most CRMs and automation tools accept this format natively.
Respond quickly. Your endpoint should return within 5 seconds. StarAgent sends webhooks fire-and-forget, so a timeout will not block call processing, but your data will be lost if your endpoint is down.

Ready to connect?

See step-by-step guides for popular platforms.

Zapier N8N Loops.so IFTTT OpenClaw