Skip to main content
🤖 LLM Friendly: This page is available in raw Markdown format for LLM consumption:event-catalog.md|Get full documentation:llms.txt/llms-full.txt

Webhook Event Catalog

Detailed payloads and schemas for all webhook events supported by Firetell.

Call Events​

call.created​

Triggered immediately when a new call (inbound or outbound) is initiated.

{
  "event": "call.created",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:00:00.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "direction": "inbound",
    "status": "started",
    "type": "audio",
    "from": {
      "name": "+84901234567",
      "number": "+84901234567"
    },
    "to": {
      "name": "Support Line",
      "number": "+84909876543"
    },
    "started_at": "2026-07-21T12:00:00.000Z",
    "answered_at": null,
    "ended_at": null,
    "duration": 0,
    "billsec": 0,
    "hangup_cause": null
  }
}

call.answered​

Triggered whenever a call transitions to answered state.

{
  "event": "call.answered",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:00:05.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "direction": "inbound",
    "status": "active",
    "type": "audio",
    "from": {
      "name": "+84901234567",
      "number": "+84901234567"
    },
    "to": {
      "name": "Support Line",
      "number": "+84909876543"
    },
    "started_at": "2026-07-21T12:00:00.000Z",
    "answered_at": "2026-07-21T12:00:05.000Z",
    "ended_at": null,
    "duration": 5,
    "billsec": 0,
    "hangup_cause": null
  }
}

call.ended​

Triggered when a call hangs up or fails.

{
  "event": "call.ended",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:02:30.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "direction": "inbound",
    "status": "completed",
    "type": "audio",
    "from": {
      "name": "+84901234567",
      "number": "+84901234567"
    },
    "to": {
      "name": "Support Line",
      "number": "+84909876543"
    },
    "started_at": "2026-07-21T12:00:00.000Z",
    "answered_at": "2026-07-21T12:00:05.000Z",
    "ended_at": "2026-07-21T12:02:30.000Z",
    "duration": 150,
    "billsec": 145,
    "hangup_cause": "NORMAL_CLEARING"
  }
}

call.recording.ready​

Triggered when audio recording processing completes and the cloud media file URL is ready for playback and download.

{
  "event": "call.recording.ready",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:02:35.000Z",
    "attempt": 1,
    "recording_id": "rec_call_abc123",
    "call_id": "call_abc123",
    "url": "https://storage.firetell.app/workspaces/ws_company/recordings/call_abc123.mp3",
    "duration": 145,
    "size_bytes": 1160000,
    "format": "mp3",
    "created_at": "2026-07-21T12:02:35.000Z"
  }
}

call.transcription.completed​

Triggered when real-time AI transcription completes and full dialogue text with extracted entities (NER) is compiled.

{
  "event": "call.transcription.completed",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:02:36.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "dialogues": [
      {
        "id": "diag_01h900000000000000000001",
        "speaker": "caller",
        "channel_index": 0,
        "text": "Hello, I would like to check my order status for #FT10294.",
        "confidence": 0.98,
        "duration_ms": 3200,
        "timestamp": "2026-07-21T12:00:10.000Z"
      },
      {
        "id": "diag_01h900000000000000000002",
        "speaker": "agent",
        "channel_index": 1,
        "text": "Certainly! I have retrieved order #FT10294 for Alex Rivera. It is scheduled for delivery today with Express Courier.",
        "confidence": 0.99,
        "duration_ms": 5400,
        "timestamp": "2026-07-21T12:00:20.000Z"
      }
    ],
    "entities": [
      {
        "type": "order_id",
        "value": "#FT10294",
        "confidence": 0.99
      },
      {
        "type": "customer_name",
        "value": "Alex Rivera",
        "confidence": 0.98
      },
      {
        "type": "carrier",
        "value": "Express Courier",
        "confidence": 0.97
      }
    ],
    "total_dialogues": 2,
    "completed_at": "2026-07-21T12:02:36.000Z"
  }
}

call.transcription.summary​

Triggered when AI post-call processing completes, providing executive call summary, customer sentiment analysis, and actionable next steps.

{
  "event": "call.transcription.summary",
  "workspace_id": "ws_company",
  "timestamp": "2026-07-21T12:02:40.000Z",
  "data": {
    "transcription_id": "trans_01h900000000000000000001",
    "call_id": "call_abc123",
    "workspace_id": "ws_company",
    "summary": "Customer inquired about enterprise cloud contact center solutions and pricing.",
    "sentiment": "positive",
    "action_items": [
      "Send Enterprise pricing sheet to customer",
      "Schedule live product demo"
    ],
    "language": "en"
  }
}

Contact Events​

contact.created​

Triggered whenever a new contact is created in the workspace.

{
  "event": "contact.created",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:10:00.000Z",
    "attempt": 1,
    "id": "ct_987654321",
    "address_book_id": "ab_sales_vip",
    "first_name": "Nguyen",
    "last_name": "Van A",
    "company": "Acme Corp",
    "phone_numbers": [
      {
        "phone_number": "+84901234567",
        "normalized_number": "84901234567",
        "type": "mobile",
        "is_primary": true
      }
    ],
    "emails": [],
    "assigned_agent_id": "ag_john",
    "created_at": "2026-07-21T12:10:00.000Z"
  }
}

contact.updated​

Triggered whenever contact details or address book assignment are modified.

{
  "event": "contact.updated",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:15:00.000Z",
    "attempt": 1,
    "id": "ct_987654321",
    "address_book_id": "ab_sales_vip",
    "first_name": "Nguyen",
    "last_name": "Van A",
    "company": "Acme Global",
    "title": "CTO",
    "updated_at": "2026-07-21T12:15:00.000Z"
  }
}

contact.deleted​

Triggered when a contact is permanently removed.

{
  "event": "contact.deleted",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:20:00.000Z",
    "attempt": 1,
    "id": "ct_987654321",
    "address_book_id": "ab_sales_vip"
  }
}

Agent Events​

agent.state​

Triggered whenever an agent's presence state (available, busy, away, offline) changes.

{
  "event": "agent.state",
  "workspace_id": "ws_company",
  "data": {
    "id": "650000000000000000000001",
    "username": "agent_john",
    "state": "busy",
    "reason": "On call",
    "changed_by": "supervisor_mary"
  },
  "timestamp": "2026-08-03T15:20:00.000Z",
  "attempt": 1
}

agent.created / agent.updated / agent.deleted​

Triggered whenever a workspace agent account is created, updated, or deleted.

{
  "event": "agent.created",
  "workspace_id": "ws_company",
  "data": {
    "id": "650000000000000000000001",
    "username": "agent_john",
    "display_name": "John Doe",
    "email": "john@company.com",
    "role": "agent",
    "avatar": "https://cdn.firetell.com/avatars/agent_john.png",
    "country_code": "US",
    "is_active": true
  },
  "timestamp": "2026-08-03T15:20:00.000Z",
  "attempt": 1
}

Workspace & Billing Events​

workspace.credit.updated​

Triggered whenever the workspace credit balance changes (e.g., when an outbound call charge is deducted or when credits are added).

{
  "event": "workspace.credit.updated",
  "workspace_id": "ws_company",
  "timestamp": "2026-08-14T11:36:00.000Z",
  "attempt": 1,
  "data": {
    "workspace_id": "ws_company",
    "credit_balance": 124.85,
    "currency": "USD",
    "amount": -0.055,
    "type": "charge",
    "description": "Outbound call to destination_number: +12025550143 (duration: 60s / 1 mins, from_number: 13133670411)",
    "call_id": "call_1786704938",
    "timestamp": "2026-08-14T11:36:00.000Z"
  }
}

Message (SMS/MMS) Events​

message.received​

Triggered when an incoming SMS or MMS message is received on one of your workspace phone numbers.

{
  "event": "message.received",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:00.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_be52701819fa34a72ae414",
    "phone_number_id": "pn_99bf875464f1c096f46aff",
    "direction": "inbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Hello, I need assistance with my reservation.",
    "status": "received",
    "media_urls": [],
    "created_at": "2026-09-26T00:00:00.000Z"
  }
}

message.sent​

Triggered when an outbound SMS or MMS message has been accepted by the telecommunications carrier and dispatched for delivery.

{
  "event": "message.sent",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:02.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "sent",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:00:02.000Z"
  }
}

message.delivered​

Triggered when the destination carrier confirms successful delivery of the message to the recipient's handset (Delivery Receipt - DLR).

{
  "event": "message.delivered",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:05.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "delivered",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:00:05.000Z"
  }
}

message.failed​

Triggered when an outbound SMS/MMS message fails to send or cannot be delivered by the carrier (e.g. invalid destination number, carrier unreachable, or message blocked).

{
  "event": "message.failed",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:04.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "failed",
    "error_code": "40001",
    "error_message": "Destination unreachable: Handset turned off or out of coverage",
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:00:04.000Z"
  }
}

message.undelivered​

Triggered when a delivery outcome could not be definitively confirmed by the carrier within the receipt timeout window.

{
  "event": "message.undelivered",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:05:00.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "undelivered",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:05:00.000Z"
  }
}