# Events This page documents all webhook events sent by KrosAI. ## Event Format All webhook events follow this structure: ```json { "event": "event.type", "id": "evt_abc123", "timestamp": "2025-01-10T12:00:00Z", "data": { // Event-specific data } } ``` ## Call Events ### call.initiated Sent when a call is initiated (inbound or outbound). ```json { "event": "call.initiated", "id": "evt_001", "timestamp": "2025-01-10T12:00:00Z", "data": { "call_id": "call_abc123", "direction": "inbound", "from_number": "+14155551234", "to_number": "+2348012345678", "phone_number_id": "pn_123", "endpoint_id": "ep_456" } } ``` ### call.ringing Sent when the destination is ringing. ```json { "event": "call.ringing", "id": "evt_002", "timestamp": "2025-01-10T12:00:01Z", "data": { "call_id": "call_abc123" } } ``` ### call.answered Sent when the call is answered. ```json { "event": "call.answered", "id": "evt_003", "timestamp": "2025-01-10T12:00:05Z", "data": { "call_id": "call_abc123", "answered_at": "2025-01-10T12:00:05Z" } } ``` ### call.completed Sent when a call ends normally. ```json { "event": "call.completed", "id": "evt_004", "timestamp": "2025-01-10T12:03:05Z", "data": { "call_id": "call_abc123", "direction": "inbound", "from_number": "+14155551234", "to_number": "+2348012345678", "duration": 180, "cost_cents": 12, "hangup_cause": "normal_clearing", "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3", "transcript": "Hello, how can I help you today?...", "metadata": { "customer_id": "cust_123" } } } ``` ### call.failed Sent when a call fails to connect. ```json { "event": "call.failed", "id": "evt_005", "timestamp": "2025-01-10T12:00:30Z", "data": { "call_id": "call_abc123", "direction": "outbound", "from_number": "+2348012345678", "to_number": "+14155551234", "error_code": "NETWORK_ERROR", "error_message": "Failed to establish connection" } } ``` ## Phone Number Events ### phone\_number.purchased Sent when a phone number is purchased. ```json { "event": "phone_number.purchased", "id": "evt_010", "timestamp": "2025-01-10T12:00:00Z", "data": { "phone_number_id": "pn_abc123", "number": "+2348012345678", "country": "NG", "type": "local", "monthly_cost_cents": 500 } } ``` ### phone\_number.released Sent when a phone number is released. ```json { "event": "phone_number.released", "id": "evt_011", "timestamp": "2025-01-10T12:00:00Z", "data": { "phone_number_id": "pn_abc123", "number": "+2348012345678" } } ``` ### phone\_number.updated Sent when a phone number configuration changes. ```json { "event": "phone_number.updated", "id": "evt_012", "timestamp": "2025-01-10T12:00:00Z", "data": { "phone_number_id": "pn_abc123", "changes": { "endpoint_id": { "old": "ep_old", "new": "ep_new" } } } } ``` ## Endpoint Events ### endpoint.created ```json { "event": "endpoint.created", "id": "evt_020", "timestamp": "2025-01-10T12:00:00Z", "data": { "endpoint_id": "ep_abc123", "name": "Support Agent", "type": "agent", "provider": "elevenlabs" } } ``` ### endpoint.updated ```json { "event": "endpoint.updated", "id": "evt_021", "timestamp": "2025-01-10T12:00:00Z", "data": { "endpoint_id": "ep_abc123", "changes": { "status": { "old": "active", "new": "inactive" } } } } ``` ### endpoint.deleted ```json { "event": "endpoint.deleted", "id": "evt_022", "timestamp": "2025-01-10T12:00:00Z", "data": { "endpoint_id": "ep_abc123" } } ``` ## Recording Events ### recording.ready Sent when a call recording is processed and available. ```json { "event": "recording.ready", "id": "evt_030", "timestamp": "2025-01-10T12:05:00Z", "data": { "call_id": "call_abc123", "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3", "duration_seconds": 180, "size_bytes": 2160000 } } ``` ### transcript.ready Sent when a call transcript is processed and available. ```json { "event": "transcript.ready", "id": "evt_031", "timestamp": "2025-01-10T12:05:30Z", "data": { "call_id": "call_abc123", "transcript": "[Agent]: Hello...", "word_count": 156, "language": "en" } } ``` ## Port Request Events ### port\_request.submitted ```json { "event": "port_request.submitted", "id": "evt_040", "timestamp": "2025-01-10T12:00:00Z", "data": { "port_request_id": "pr_abc123", "phone_number": "+2348012345678", "current_carrier": "mtn" } } ``` ### port\_request.completed ```json { "event": "port_request.completed", "id": "evt_041", "timestamp": "2025-01-25T10:00:00Z", "data": { "port_request_id": "pr_abc123", "phone_number_id": "pn_new123", "phone_number": "+2348012345678" } } ``` ### port\_request.failed ```json { "event": "port_request.failed", "id": "evt_042", "timestamp": "2025-01-15T14:00:00Z", "data": { "port_request_id": "pr_abc123", "reason": "Account name mismatch", "phone_number": "+2348012345678" } } ``` ## Billing Events ### balance.low Sent when account balance falls below threshold. ```json { "event": "balance.low", "id": "evt_050", "timestamp": "2025-01-10T12:00:00Z", "data": { "current_balance_cents": 500, "threshold_cents": 1000 } } ``` ### payment.received ```json { "event": "payment.received", "id": "evt_051", "timestamp": "2025-01-10T12:00:00Z", "data": { "amount_cents": 10000, "payment_method": "card", "new_balance_cents": 10500 } } ``` ## Event Subscriptions Configure which events to receive when creating a webhook: ```bash curl -X POST "https://api.krosai.com/v1/webhooks" \ -H "x-api-key: kros_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.yourapp.com/webhooks/krosai", "events": [ "call.completed", "call.failed", "recording.ready" ] }' ``` ### Event Wildcards Subscribe to all events in a category: * `call.*` - All call events * `phone_number.*` - All phone number events * `*` - All events --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.krosai.com/webhooks/events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.