Skip to content
Talki DevelopersBeta

call.updated

POST

A call is marked read or unread, archived or returned to the inbox, by hand or by the owner’s auto-archive window. One event per call. Sent to the account’s webhooks, and to an OAuth app that subscribes to it while its installation grants calls:read.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
X-Talki-Signature
required
string

t=<unix seconds>,v1=<hex HMAC-SHA256>, the HMAC computed over <t>.<raw body> with the signing secret. During a secret rotation it carries one v1 per secret: accept the request if any matches.

X-Talki-Event
required
string

The event type, as in type.

X-Talki-Delivery
required
string

The event ID, as in id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
id
required
Id

The event’s ID, evt_ and 32 hex characters. Equal to the X-Talki-Delivery header and unchanged on a redelivery: deduplicate on it.

string
type
required
string
Allowed values: call.updated
created_at
required
Created At

When the event was written, ISO 8601 with a +00:00 offset, possibly with microseconds. Parse it as an instant.

string format: date-time
api_version
required
Api Version

The dated contract version data is shaped for: the endpoint’s version on a webhook, the app’s on an app event.

string
account_id
required
Account Id

The Talki account the event happened on.

string
livemode
required
Livemode

false for an event from a sandbox account.

boolean
origin
required
Any of:
EventOrigin
object
source
required
Source

Where the change came from: voice (the assistant, during a call), dashboard (a person in the Talki web or mobile app), api (a credential through the API) or system (a rule Talki applied on its own). New values may be added; treat one you do not recognise as unknown.

string
credential_id
required
Any of:
string
idempotency_key
required
Any of:
string
installation_id
Any of:
string
data
required

The event’s payload.

object
object
required

The Call object, as the REST API returns it.

object
id
required
Id

Opaque Talki call identifier. Decided when the call arrives: the call.ringing event sent while it rang carries the same id as data.call_id.

string
location_id
required
Location Id

The location the call was for: the one whose Talki number the caller dialled (GET /v1/locations). Never null: a call to the account’s own number, and every call from before locations existed, is the main location’s. It never changes.

string
caller
required
CallCaller

Who called, as far as the account knows. Always present; its fields may be null. display_name is set only for a name the owner entered or imported, never for one the assistant heard.

object
contact_id
required
Any of:
string
phone_number
required
Any of:
string
display_name
required
Any of:
string
started_at
required
Started At

When the call ARRIVED, before the assistant picked up. RFC 3339 UTC. This is the ordering key for GET /v1/calls.

string format: date-time
answered_at
required
Any of:
string format: date-time
ended_at
required
Any of:
string format: date-time
duration_seconds
required
Any of:
integer
summary
required
Any of:
string
appointment_ids
required
Appointment Ids

Appointments booked during this call, oldest first. Empty for a call that booked nothing. Includes appointments since cancelled — the link records what the call did, not the appointment’s current state.

Array<string>
outcome
required
Any of:
string
transfers
required
Any of:
Array<object>
CallTransfer

A hand-over of the call to a person, in the order it happened.

object
target_label
required
Target Label

The destination as the owner named it in Talki (e.g. Reception). Never the number behind it. Compare it case-insensitively.

string
at
required
Any of:
string format: date-time
appointment_changes
required
Any of:
Array<object>
CallAppointmentChange

An existing appointment the call moved or cancelled.

object
appointment_id
required
Appointment Id

The appointment.

string
action
required
Action

rescheduled or cancelled.

string
unresolved_request_ids
required
Any of:
Array<string>
created_at
required
Created At

When this record was written, RFC 3339 UTC: after the call ended, so a long call can be written after a shorter call that started later. created_after filters on this field. Do not use it as a sync watermark: records do not become visible in created_at order, so a watermark on it can skip a call permanently. Resume a sync with GET /v1/calls?sync=true and its cursor.

string format: date-time
read_at
required
Any of:
string format: date-time
archived_at
required
Any of:
string format: date-time
Example
{
  "id": "evt_04d8e87897db4ecab459a456ea55e754",
  "type": "call.updated",
  "created_at": "2026-09-22T15:04:06.218734+00:00",
  "api_version": "2026-10-01",
  "account_id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
  "livemode": true,
  "origin": {
    "source": "dashboard",
    "credential_id": null,
    "idempotency_key": null
  },
  "data": {
    "object": {
      "id": "38d23d84-02d2-4418-b169-3608aa04a8f8",
      "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40",
      "caller": {
        "contact_id": "8fbb25f2-4f3b-4496-8aea-f0fc66de512d",
        "phone_number": "+393331234567",
        "display_name": "Giulia Bianchi"
      },
      "started_at": "2026-09-15T09:14:31Z",
      "answered_at": "2026-09-15T09:14:34Z",
      "ended_at": "2026-09-15T09:18:02Z",
      "duration_seconds": 208,
      "summary": "Giulia booked a haircut for the morning of 8 October.",
      "appointment_ids": [
        "a3fe45ee-572f-4677-b1dd-f36c21bb47de"
      ],
      "outcome": "booked",
      "transfers": [],
      "appointment_changes": [],
      "unresolved_request_ids": [],
      "created_at": "2026-09-15T09:18:03Z",
      "read_at": "2026-09-15T10:02:11Z",
      "archived_at": null
    }
  }
}

Responses

Section titled “ Responses ”

2XX

Section titled “2XX”

Any 2xx acknowledges the event. Any other status, a redirect, or no answer within 10 seconds is a failure and is retried; 410 disables a webhook endpoint at once.