openapi: 3.1.0 info: title: Talki API version: '2026-10-01' summary: Sync calls, contacts, services and appointments with Talki. description: The private-beta Talki REST API. Read change feeds, check availability, and make narrowly scoped writes with an account API key or an OAuth access token. API access requires a Business plan. contact: name: Talki support email: info@talki.it paths: /v1/account: get: tags: - Account summary: Retrieve the authenticated account description: Validate the API key and return the Talki account it belongs to, with everything `PATCH /v1/account` can change, the Talki number and the onboarding state. Requires `account:read`. Limited to 60 requests per minute per account (API key) or per installation (OAuth). operationId: getAccount security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location whose settings to read, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location whose settings to read, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: &id001 type: string example: '2026-10-01' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Account' example: &id009 id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 business_name: Studio Bellini timezone: Europe/Rome livemode: true test: false business_information: Free parking in the courtyard behind the salon. We do not sell gift cards. instructions: null voice: Sulafat answers_as: business call_auto_archive_days: null greeting: null call_opening: null multilingual_enabled: true languages: &id002 primary: it supported: - it - en - fr - de - es service_area: Bergamo e provincia transfer_numbers: [] bookings_enabled: true unresolved_requests_enabled: true remember_callers: true store_transcripts: true notify_on_every_call: true notify_on_incoming_call: false phone_number: '+390350000001' forwarding_number: '+393331112222' line: &id004 phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' multi_sede: true onboarding_completed: true headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' ETag: description: Strong entity tag of the writable content. Send it as `If-Match` on the next write. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: &id005 description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: &id006 description: The budget of the window that was exceeded. Absent on `ip_rate_limited`. schema: &id026 type: string X-RateLimit-Remaining: &id007 description: Requests left in the window. Absent on `ip_rate_limited`. schema: &id027 type: integer X-RateLimit-Reset: &id008 description: When the window resets, in Unix seconds. Absent on `ip_rate_limited`. schema: &id028 type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/account' \\\ \n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() account = talki.account.get() print(account)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const account = await talki.account.get(); console.log(account);' patch: tags: - Account summary: Update the assistant settings description: 'Change any of the account''s writable fields: the assistant''s settings, the transfer numbers or the forwarding number. Omitted fields stay unchanged; a body with none of them is refused. A custom `call_opening` needs a plan that includes it, and `store_transcripts: false` is refused with a test-mode credential. Send `If-Match` with the `ETag` of your last read to be refused rather than overwrite a change made since. Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: updateAccount security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location whose settings to change, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location whose settings to change, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: assistant-settings-2026-10 - name: If-Match in: header required: false description: The `ETag` of your last read. If the stored version is a different one, the write is refused with `412 precondition_failed`, unless it asks for exactly what is already stored, so retrying a write that succeeded is safe. `*` always matches; a weak tag (`W/…`) never does. Without it, the write replaces whatever is stored. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AccountUpdate' example: instructions: Always use the formal register. Never quote prices for colour treatments. voice: Sulafat greeting: Come posso aiutarla? transfer_numbers: &id003 - label: Reception phone: '+390351234567' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Account' example: id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 business_name: Studio Bellini timezone: Europe/Rome livemode: true test: false business_information: Free parking in the courtyard behind the salon. We do not sell gift cards. instructions: Always use the formal register. Never quote prices for colour treatments. voice: Sulafat answers_as: business call_auto_archive_days: null greeting: Come posso aiutarla? call_opening: null multilingual_enabled: true languages: *id002 service_area: Bergamo e provincia transfer_numbers: *id003 bookings_enabled: true unresolved_requests_enabled: true remember_callers: true store_transcripts: true notify_on_every_call: true notify_on_incoming_call: false phone_number: '+390350000001' forwarding_number: '+393331112222' line: *id004 multi_sede: true onboarding_completed: true headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' ETag: description: Strong entity tag of the writable content. Send it as `If-Match` on the next write. Absent on a response replayed from an `Idempotency-Key`; read again for a current one. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '412': description: '`If-Match` names a version other than the stored one: the settings changed since you read them. Read them again, reapply your change, and retry with the new `ETag`.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: precondition_failed message: This resource changed after the version named in If-Match. Fetch it again, reapply your change, and retry with the new ETag. request_id: req_7f24a2f8c6b64e699901563a458b5031 '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: This account's plan does not include a custom `call_opening` (`plan_feature_unavailable`), or the credential lacks the scope (`insufficient_scope`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: plan_feature_unavailable message: This account's plan does not include a custom `call_opening`. Clearing it is allowed on every plan. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: No writable field was sent, or a value is invalid (`invalid_parameter`). That includes a `forwarding_number` equal to a transfer target of any location or to another location's line, a non-empty `transfer_numbers` while the main location has no `forwarding_number` stored or sent, a transfer target equal to a location's line, and clearing the main location's `forwarding_number` while any location has `transfer_numbers`; this location's may be replaced in the same request. `Talki-Version` may also name an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: '`forwarding_number` is one of the `transfer_numbers`: a call transferred there would come straight back to the assistant. Remove it from `transfer_numbers` first, or in the same request.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: '`store_transcripts: false` was sent with a test-mode credential (`livemode_required`), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: livemode_required message: '`store_transcripts: false` deletes the account''s stored transcripts for good, so it is not available in test mode.' request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/account'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ assistant-settings-2026-10\" \\\n -H \"Content-Type: application/json\"\ \ \\\n --data '{\"instructions\":\"Always use the formal register. Never\ \ quote prices for colour treatments.\",\"voice\":\"Sulafat\",\"greeting\"\ :\"Come posso aiutarla?\",\"transfer_numbers\":[{\"label\":\"Reception\"\ ,\"phone\":\"+390351234567\"}]}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\naccount = talki.account.update(\n\ \ body={\n \"instructions\": \"Always use the formal register.\ \ Never quote prices for colour treatments.\",\n \"voice\": \"Sulafat\"\ ,\n \"greeting\": \"Come posso aiutarla?\",\n \"transfer_numbers\"\ : [{\"label\": \"Reception\", \"phone\": \"+390351234567\"}],\n },\n\ \ idempotency_key=\"assistant-settings-2026-10\",\n)\nprint(account)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst account = await talki.account.update({\n body: {\n instructions:\ \ \"Always use the formal register. Never quote prices for colour treatments.\"\ ,\n voice: \"Sulafat\",\n greeting: \"Come posso aiutarla?\",\n \ \ transfer_numbers: [{ label: \"Reception\", phone: \"+390351234567\" }],\n\ \ },\n idempotencyKey: \"assistant-settings-2026-10\",\n});\nconsole.log(account);" /v1/account/complete_onboarding: post: tags: - Account summary: Complete onboarding description: Mark the account's setup as finished, so the Talki app does not open its setup wizard. Idempotent; it is never undone. Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: completeOnboarding responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Account' example: *id009 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' ETag: description: Strong entity tag of the writable content. Send it as `If-Match` on the next write. Absent on a response replayed from an `Idempotency-Key`; read again for a current one. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/account/complete_onboarding'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ onboarding-done\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() account = talki.account.complete_onboarding(idempotency_key="onboarding-done") print(account)' - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst account = await talki.account.completeOnboarding({\n idempotencyKey:\ \ \"onboarding-done\",\n});\nconsole.log(account);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: onboarding-done /v1/locations: get: tags: - Locations summary: List locations description: 'Return every location of the account in one page: the main one, any other, and inactive ones, which keep their records. An account whose `multi_sede` is false has exactly one, the main location. Resolve the `location_id` on calls, bookings, services, resources, unresolved requests and closures here. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' operationId: listLocations responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LocationList' example: data: - id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Studio Bellini is_default: true status: active phone_number: '+390350000001' line: *id004 position: 0 created_at: '2026-08-01T08:00:00Z' deactivated_at: null - id: a6e3c2d8-1f47-4b95-8e0a-3d9c6b1f7a52 name: Borgo Trento is_default: false status: active phone_number: '+390350000002' line: phone_number: '+390350000002' forwarding_number: '+390451234567' status: unverified verified_at: null position: 1 created_at: '2026-10-12T09:40:00Z' deactivated_at: null next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/locations'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() location_list = talki.locations.list() print(location_list)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const locationList = await talki.locations.list(); console.log(locationList);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 /v1/calls/stats: get: tags: - Calls summary: Retrieve call statistics description: Return totals, the daily series and the top callers over the last `days`, or over the local days `from` to `to` (at most 366). Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: getCallStats security: - ApiKeyAuth: [] parameters: - name: days in: query required: false schema: anyOf: - type: integer maximum: 365 minimum: 1 - type: 'null' description: 'Length of the period, in days, ending now. Default 30. It starts at the same local time, in the account''s `timezone`, `days` days earlier: across a daylight-saving change, an hour more or less than `days` × 24 hours. Cannot be combined with `from` / `to`.' title: Days description: 'Length of the period, in days, ending now. Default 30. It starts at the same local time, in the account''s `timezone`, `days` days earlier: across a daylight-saving change, an hour more or less than `days` × 24 hours. Cannot be combined with `from` / `to`.' - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: First day of the period, `YYYY-MM-DD`, local to the account's `timezone`. Sent with `to`, instead of `days`. title: From description: First day of the period, `YYYY-MM-DD`, local to the account's `timezone`. Sent with `to`, instead of `days`. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Last day of the period, included, `YYYY-MM-DD`. At most 366 days after `from`. title: To description: Last day of the period, included, `YYYY-MM-DD`. At most 366 days after `from`. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for every location. title: Location Id description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallStats' example: period_days: 30 period_start: '2026-09-07T22:00:00Z' period_end: '2026-10-07T22:00:00Z' total_calls: 142 total_duration_seconds: 21480 average_duration_seconds: 151.3 booked_calls: 61 unresolved_calls: 9 transferred_calls: 7 today: 4 this_week: 23 this_month: 38 daily: - date: '2026-10-07' calls: 4 duration_seconds: 612 top_callers: - phone_number: '+393331234567' calls: 5 duration_seconds: 840 last_call_at: '2026-10-07T08:41:09Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/stats?days=30'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() call_stats = talki.calls.get_stats(days=30) print(call_stats)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const callStats = await talki.calls.getStats({ days: 30 }); console.log(callStats);' /v1/calls/count: get: tags: - Calls summary: Count calls description: Count the calls in one inbox view. `status=unread` is the unread badge. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: countCalls security: - ApiKeyAuth: [] parameters: - name: status in: query required: false schema: allOf: - $ref: '#/components/schemas/InboxStatus' description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` — every call (the default).' default: all description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` — every call (the default).' - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for every location. title: Location Id description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallCount' example: total: 3 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/count?status=unread'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki from talki.models import InboxStatus talki = Talki() call_count = talki.calls.count(status=InboxStatus.UNREAD) print(call_count)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const callCount = await talki.calls.count({ status: "unread" }); console.log(callCount);' /v1/calls/export: get: tags: - Calls summary: Export the call log description: Return the calls of a date range as a PDF or Excel file, without transcripts. `status` defaults to `all`; `status`, `q` and `outcome` narrow the file as they narrow `GET /v1/calls`. Each call's appointments are included only when the credential also holds `appointments:read`. Needs a plan that includes the call log export. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth), and to 10 file exports per minute. operationId: exportCalls security: - ApiKeyAuth: [] parameters: - name: from in: query required: true schema: type: string description: First day, `YYYY-MM-DD`, local to the account's `timezone`. format: date title: From description: First day, `YYYY-MM-DD`, local to the account's `timezone`. - name: to in: query required: true schema: type: string description: Last day, included, `YYYY-MM-DD`. At most 366 days after `from`. format: date title: To description: Last day, included, `YYYY-MM-DD`. At most 366 days after `from`. - name: format in: query required: false schema: allOf: - $ref: '#/components/schemas/ExportFormat' description: '`pdf` for a document (the default), `xlsx` for an Excel sheet.' default: pdf description: '`pdf` for a document (the default), `xlsx` for an Excel sheet.' - name: status in: query required: false schema: allOf: - $ref: '#/components/schemas/InboxStatus' description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` — every call (the default).' default: all description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` — every call (the default).' - name: q in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Search, 2 to 100 characters, ignoring case: calls whose `summary` contains it, or whose caller''s `display_name` does. A name that is not published as `display_name` is not searched either.' title: Q description: 'Search, 2 to 100 characters, ignoring case: calls whose `summary` contains it, or whose caller''s `display_name` does. A name that is not published as `display_name` is not searched either.' - name: outcome in: query required: false schema: anyOf: - $ref: '#/components/schemas/CallOutcome' - type: 'null' description: 'Only calls with this `outcome`: `booked`, `rescheduled`, `cancelled`, `transferred`, `unresolved`, `info`. Calls recorded before outcomes were tracked have none and match no value.' title: Outcome description: 'Only calls with this `outcome`: `booked`, `rescheduled`, `cancelled`, `transferred`, `unresolved`, `info`. Calls recorded before outcomes were tracked have none and match no value.' - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for every location. title: Location Id description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: The file, as an attachment. content: application/pdf: schema: type: string format: binary application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: This account's plan does not include exporting a date range (`plan_feature_unavailable`), or the credential lacks the scope (`insufficient_scope`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: plan_feature_unavailable message: This account's plan does not include exporting the call log over a date range. A single call can be exported on every plan. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: 'A parameter is invalid (`invalid_parameter`), or the range holds more than 5000 calls (`export_too_large`): narrow the dates.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: export_too_large message: The range holds more than 5000 calls. Narrow the dates. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/export?from=2026-09-01&to=2026-09-30&format=xlsx'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n --output calls.xlsx" - lang: python label: Python source: "from datetime import date\nfrom pathlib import Path\n\nfrom talki\ \ import Talki\nfrom talki.models import ExportFormat\n\ntalki = Talki()\n\ \nfile = talki.calls.export_calls(\n from_=date(2026, 9, 1),\n to=date(2026,\ \ 9, 30),\n format_=ExportFormat.XLSX,\n)\nPath(\"calls.xlsx\").write_bytes(file.payload.read())" - lang: ts label: TypeScript source: "import { writeFile } from \"node:fs/promises\";\nimport { Talki }\ \ from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\nconst file =\ \ await talki.calls.exportCalls({\n from: \"2026-09-01\",\n to: \"2026-09-30\"\ ,\n format: \"xlsx\",\n});\nawait writeFile(\"calls.xlsx\", new Uint8Array(await\ \ file.arrayBuffer()));" /v1/calls/{call_id}/export: get: tags: - Calls summary: Export a call description: Return one call as a PDF or Excel file, on every plan. It includes the conversation only with `transcripts:read` and when the account keeps transcripts, and the call's appointments only with `appointments:read`. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth), and to 10 file exports per minute. operationId: exportCall security: - ApiKeyAuth: [] parameters: - name: call_id in: path required: true schema: type: string title: Call Id - name: format in: query required: false schema: allOf: - $ref: '#/components/schemas/ExportFormat' description: '`pdf` for a document (the default), `xlsx` for an Excel sheet.' default: pdf description: '`pdf` for a document (the default), `xlsx` for an Excel sheet.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: The file, as an attachment. content: application/pdf: schema: type: string format: binary application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No call with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such call. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/38d23d84-02d2-4418-b169-3608aa04a8f8/export?format=pdf'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n --output call.pdf" - lang: python label: Python source: "from pathlib import Path\n\nfrom talki import Talki\nfrom talki.models\ \ import ExportFormat\n\ntalki = Talki()\n\nfile = talki.calls.export_call(\n\ \ \"38d23d84-02d2-4418-b169-3608aa04a8f8\",\n format_=ExportFormat.PDF,\n\ )\nPath(\"call.pdf\").write_bytes(file.payload.read())" - lang: ts label: TypeScript source: "import { writeFile } from \"node:fs/promises\";\nimport { Talki }\ \ from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\nconst file =\ \ await talki.calls.exportCall(\"38d23d84-02d2-4418-b169-3608aa04a8f8\"\ , {\n format: \"pdf\",\n});\nawait writeFile(\"call.pdf\", new Uint8Array(await\ \ file.arrayBuffer()));" /v1/refused_calls: get: tags: - Calls summary: List refused calls description: Return the calls Talki refused before answering, newest first. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listRefusedCalls security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of refused calls to return. default: 50 title: Limit description: Maximum number of refused calls to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. title: Cursor description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the refused calls of this location (`RefusedCall.location_id`), an id from `GET /v1/locations`. Omit for every location. title: Location Id description: Only the refused calls of this location (`RefusedCall.location_id`), an id from `GET /v1/locations`. Omit for every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RefusedCallList' example: data: - id: 5e2c8a71-9b4d-4f36-a0e1-c7d3b9f2e584 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 caller: contact_id: null phone_number: '+393409876543' display_name: null dialled_number: '+390350000001' reason: minutes action: upgrade_plan attempted_at: '2026-10-06T17:22:40Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/refused_calls?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.calls.list_refused(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.calls.listRefused({ limit: 10 }); console.log(page.data);' /v1/refused_calls/count: get: tags: - Calls summary: Count refused calls operationId: countRefusedCalls security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the refused calls of this location (`RefusedCall.location_id`), an id from `GET /v1/locations`. Omit for every location. title: Location Id description: Only the refused calls of this location (`RefusedCall.location_id`), an id from `GET /v1/locations`. Omit for every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallCount' example: total: 1 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Count every refused call the account has. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/refused_calls/count'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() call_count = talki.calls.count_refused() print(call_count)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const callCount = await talki.calls.countRefused(); console.log(callCount);' /v1/refused_calls/summary: get: tags: - Calls summary: Summarise refused calls description: Return refused calls over the last `days`, or over the local days `from` to `to`, by reason, and the actions they call for. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: getRefusedCallSummary security: - ApiKeyAuth: [] parameters: - name: days in: query required: false schema: anyOf: - type: integer maximum: 365 minimum: 1 - type: 'null' description: 'Length of the period, in days, ending now. Default 30. It starts at the same local time, in the account''s `timezone`, `days` days earlier: across a daylight-saving change, an hour more or less than `days` × 24 hours. Cannot be combined with `from` / `to`.' title: Days description: 'Length of the period, in days, ending now. Default 30. It starts at the same local time, in the account''s `timezone`, `days` days earlier: across a daylight-saving change, an hour more or less than `days` × 24 hours. Cannot be combined with `from` / `to`.' - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: First day of the period, `YYYY-MM-DD`, local to the account's `timezone`. Sent with `to`, instead of `days`. title: From description: First day of the period, `YYYY-MM-DD`, local to the account's `timezone`. Sent with `to`, instead of `days`. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Last day of the period, included, `YYYY-MM-DD`. At most 366 days after `from`. title: To description: Last day of the period, included, `YYYY-MM-DD`. At most 366 days after `from`. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the refused calls of this location (`RefusedCall.location_id`), an id from `GET /v1/locations`. Omit for every location. title: Location Id description: Only the refused calls of this location (`RefusedCall.location_id`), an id from `GET /v1/locations`. Omit for every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RefusedCallSummary' example: period_days: 30 period_start: '2026-09-07T22:00:00Z' period_end: '2026-10-07T22:00:00Z' total: 1 by_reason: minutes: 1 recent: 1 recent_days: 7 actions: - upgrade_plan headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/refused_calls/summary?days=30'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() refused_call_summary = talki.calls.get_refused_summary(days=30) print(refused_call_summary)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const refusedCallSummary = await talki.calls.getRefusedSummary({ days: 30 }); console.log(refusedCallSummary);' /v1/calls: get: tags: - Calls summary: List calls operationId: listCalls security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of calls to return. default: 50 title: Limit description: Maximum number of calls to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. A cursor works only in the mode that issued it (`sync=true` or the default list); a cursor from the other mode is refused. title: Cursor description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. A cursor works only in the mode that issued it (`sync=true` or the default list); a cursor from the other mode is refused. - name: sync in: query required: false schema: type: boolean description: 'Switch to the CHANGE FEED: ordered by when each record was committed, not by when the call started, and resumable exactly like `GET /v1/appointments`. This is how a system keeping its own copy recovers from missed webhooks — store `next_cursor`, which is returned on the last page too, and drive the loop from `has_more`. Leave it off for the newest-first list a person reads.' default: false title: Sync description: 'Switch to the CHANGE FEED: ordered by when each record was committed, not by when the call started, and resumable exactly like `GET /v1/appointments`. This is how a system keeping its own copy recovers from missed webhooks — store `next_cursor`, which is returned on the last page too, and drive the loop from `has_more`. Leave it off for the newest-first list a person reads.' - name: created_after in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: 'Only calls recorded at or after this instant (RFC 3339 UTC). Inclusive: a call at exactly this instant is returned, so dedupe on `id`. Filters on `created_at`, not `started_at` (see `Call.created_at`). Use it for reporting windows, not as a sync watermark: a timestamp watermark can skip a call permanently. Use `sync=true` to resume a sync; the two cannot be combined.' title: Created After description: 'Only calls recorded at or after this instant (RFC 3339 UTC). Inclusive: a call at exactly this instant is returned, so dedupe on `id`. Filters on `created_at`, not `started_at` (see `Call.created_at`). Use it for reporting windows, not as a sync watermark: a timestamp watermark can skip a call permanently. Use `sync=true` to resume a sync; the two cannot be combined.' - name: created_before in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Only calls recorded strictly before this instant (RFC 3339 UTC). title: Created Before description: Only calls recorded strictly before this instant (RFC 3339 UTC). - name: status in: query required: false schema: allOf: - $ref: '#/components/schemas/InboxStatus' description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` (the default) — every call. Only `all` combines with `sync=true`.' default: all description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` (the default) — every call. Only `all` combines with `sync=true`.' - name: phone in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only calls from this number: E.164, or a national number read as Italian. Not with `sync=true`.' title: Phone description: 'Only calls from this number: E.164, or a national number read as Italian. Not with `sync=true`.' - name: contact_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only calls from this contact's number (`caller.contact_id`). Not with `sync=true`. title: Contact Id description: Only calls from this contact's number (`caller.contact_id`). Not with `sync=true`. - name: q in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Search, 2 to 100 characters, ignoring case: calls whose `summary` contains it, or whose caller''s `display_name` does. A name that is not published as `display_name` is not searched either. Not with `sync=true`.' title: Q description: 'Search, 2 to 100 characters, ignoring case: calls whose `summary` contains it, or whose caller''s `display_name` does. A name that is not published as `display_name` is not searched either. Not with `sync=true`.' - name: outcome in: query required: false schema: anyOf: - $ref: '#/components/schemas/CallOutcome' - type: 'null' description: 'Only calls with this `outcome`: `booked`, `rescheduled`, `cancelled`, `transferred`, `unresolved`, `info`. Calls recorded before outcomes were tracked have none and match no value. Not with `sync=true`.' title: Outcome description: 'Only calls with this `outcome`: `booked`, `rescheduled`, `cancelled`, `transferred`, `unresolved`, `info`. Calls recorded before outcomes were tracked have none and match no value. Not with `sync=true`.' - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallList' example: data: - &id010 id: 38d23d84-02d2-4418-b169-3608aa04a8f8 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 caller: &id011 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: &id012 - a3fe45ee-572f-4677-b1dd-f36c21bb47de outcome: booked transfers: &id013 [] appointment_changes: &id014 [] unresolved_request_ids: &id015 [] created_at: '2026-09-15T09:18:03Z' read_at: '2026-09-15T10:02:11Z' archived_at: null next_cursor: c1.sample has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Read the newest-first call log, or set `sync=true` for a resumable change feed. Search the log with `phone`, `contact_id`, `q` or `outcome`; they do not combine with `sync=true`. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.calls.list(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.calls.list({ limit: 10 }); console.log(page.data);' /v1/calls/{call_id}: get: tags: - Calls summary: Retrieve a call operationId: getCall security: - ApiKeyAuth: [] parameters: - name: call_id in: path required: true schema: type: string title: Call Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Call' example: *id010 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No call with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such call. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one call belonging to the authenticated account. Requires `calls:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/38d23d84-02d2-4418-b169-3608aa04a8f8'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() call = talki.calls.get("38d23d84-02d2-4418-b169-3608aa04a8f8") print(call)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const call = await talki.calls.get("38d23d84-02d2-4418-b169-3608aa04a8f8"); console.log(call);' patch: tags: - Calls summary: Update a call's inbox state description: Mark a call read or unread, archive it or return it to the inbox. Archiving marks it read. Requires `calls:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateCall security: - ApiKeyAuth: [] parameters: - name: call_id in: path required: true schema: type: string title: Call Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: call-archive-1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallUpdate' example: archived: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Call' example: id: 38d23d84-02d2-4418-b169-3608aa04a8f8 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 caller: *id011 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: *id012 outcome: booked transfers: *id013 appointment_changes: *id014 unresolved_request_ids: *id015 created_at: '2026-09-15T09:18:03Z' read_at: '2026-09-15T10:02:11Z' archived_at: '2026-10-08T07:58:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No call with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such call. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/calls/38d23d84-02d2-4418-b169-3608aa04a8f8'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ call-archive-1\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"archived\":true}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ncall = talki.calls.update(\n\ \ \"38d23d84-02d2-4418-b169-3608aa04a8f8\",\n body={\"archived\":\ \ True},\n idempotency_key=\"call-archive-1\",\n)\nprint(call)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst call = await talki.calls.update(\"38d23d84-02d2-4418-b169-3608aa04a8f8\"\ , {\n body: { archived: true },\n idempotencyKey: \"call-archive-1\",\n\ });\nconsole.log(call);" delete: tags: - Calls summary: Delete a call description: 'Delete a call for good, when the caller asks to be forgotten: the call, its transcript, the questions it left and the pending contacts it proposed. The appointments it booked stay, with `call_id` null. The talk time it used stays on the meter of `GET /v1/usage` and, for a partner-managed account, in the partner''s usage report; `GET /v1/usage/history` and the call statistics no longer count the call. Sends `call.deleted`. Requires `calls:delete`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: deleteCall security: - ApiKeyAuth: [] parameters: - name: call_id in: path required: true schema: type: string title: Call Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: call-delete-1 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account is in its free trial (`forbidden`), or the credential or account may not make this request (`insufficient_scope`, `plan_upgrade_required`, `account_closed`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: forbidden message: Calls cannot be deleted during the free trial. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No call with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such call. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'A test-mode credential was used (`livemode_required`), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: livemode_required message: Deleting a call removes it and its transcript for good, so it is not available in test mode. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/calls/38d23d84-02d2-4418-b169-3608aa04a8f8'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ call-delete-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.calls.delete(\n\ \ \"38d23d84-02d2-4418-b169-3608aa04a8f8\",\n idempotency_key=\"call-delete-1\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.calls.delete(\"38d23d84-02d2-4418-b169-3608aa04a8f8\", {\n\ \ idempotencyKey: \"call-delete-1\",\n});" /v1/calls/{call_id}/transcript: get: tags: - Calls summary: Retrieve a call transcript description: 'Return the automatic transcript of one call. `calls:read` does not grant it: the account owner ticks `transcripts:read` on its own. Requires `transcripts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' operationId: getCallTranscript security: - ApiKeyAuth: [] parameters: - name: call_id in: path required: true schema: type: string title: Call Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallTranscript' example: call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 utterances: - speaker: assistant text: Buongiorno, sta parlando con Talki, l'assistente virtuale di Studio Bellini. offset_ms: 0 duration_ms: 4200 interrupted: false unreliable: false retranscribed: false - speaker: caller text: Buongiorno, vorrei prenotare un taglio per l'8 ottobre, in mattinata. offset_ms: 4900 duration_ms: 3600 interrupted: false unreliable: false retranscribed: false source: gemini_live_sidechannel language_hint: auto assembler: 2 created_at: '2026-09-15T09:18:03Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: 'No call with this ID exists in the authenticated account (`resource_not_found`), or the call has no transcript (`transcript_not_available`): the account does not keep transcripts, or nothing usable was said. Retrying does not change a `transcript_not_available`.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: transcript_not_available message: This call has no transcript. The account may not keep transcripts, or nothing usable was said on the call. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/38d23d84-02d2-4418-b169-3608aa04a8f8/transcript'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() call_transcript = talki.calls.get_transcript("38d23d84-02d2-4418-b169-3608aa04a8f8") print(call_transcript)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const callTranscript = await talki.calls.getTranscript("38d23d84-02d2-4418-b169-3608aa04a8f8"); console.log(callTranscript);' /v1/calls/mark_all_read: post: tags: - Calls summary: Mark all calls read description: Mark every unread call in the inbox read. Each one sends `call.updated`. Requires `calls:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: markAllCallsRead security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for the calls of every location. title: Location Id description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations`. Omit for the calls of every location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: calls-read-2026-10-08 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MarkAllReadResult' example: updated: 3 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/calls/mark_all_read'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ calls-read-2026-10-08\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nmark_all_read_result\ \ = talki.calls.mark_all_read(\n idempotency_key=\"calls-read-2026-10-08\"\ ,\n)\nprint(mark_all_read_result)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst markAllReadResult = await talki.calls.markAllRead({\n idempotencyKey:\ \ \"calls-read-2026-10-08\",\n});\nconsole.log(markAllReadResult);" /v1/appointments: get: tags: - Appointments summary: List appointment changes operationId: listAppointments security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of appointments to return. default: 50 title: Limit description: Maximum number of appointments to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading everything. Not interchangeable with a `GET /v1/calls` cursor.' title: Cursor description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading everything. Not interchangeable with a `GET /v1/calls` cursor.' - name: status in: query required: false schema: anyOf: - $ref: '#/components/schemas/AppointmentStatus' - type: 'null' description: Restrict to `active` or `cancelled`. Omit to get both — which is what an incremental sync needs, since a cancellation is a change you must see. Use this only for a point-in-time snapshot. title: Status description: Restrict to `active` or `cancelled`. Omit to get both — which is what an incremental sync needs, since a cancellation is a change you must see. Use this only for a point-in-time snapshot. - name: starts_after in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Only appointments starting at or after this instant (RFC 3339 UTC). A filter on WHEN THE BOOKING IS, not on when it changed; it does not affect ordering and must not be used as a sync watermark. title: Starts After description: Only appointments starting at or after this instant (RFC 3339 UTC). A filter on WHEN THE BOOKING IS, not on when it changed; it does not affect ordering and must not be used as a sync watermark. - name: starts_before in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Only appointments starting strictly before this instant (RFC 3339 UTC). title: Starts Before description: Only appointments starting strictly before this instant (RFC 3339 UTC). - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AppointmentList' example: data: - &id016 id: a3fe45ee-572f-4677-b1dd-f36c21bb47de location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: active client: &id029 contact_id: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d name: Giulia surname: Bianchi phone_number: '+393331234567' service: &id030 id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 name: Haircut start_at: '2026-10-08T09:00:00Z' end_at: '2026-10-08T09:30:00Z' quantity: 1 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 notes: First visit created_at: '2026-09-15T09:18:03Z' updated_at: '2026-09-15T09:18:03Z' next_cursor: s1.sample has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Walk the appointment change feed in commit order. Store `next_cursor` even on the last non-empty page. Requires `appointments:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/appointments?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.appointments.list(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.appointments.list({ limit: 10 }); console.log(page.data);' post: tags: - Appointments summary: Create an appointment description: Book through the same capacity rules as the Talki assistant, at the location of the service (the main location without one). A service of an inactive location is refused with `location_inactive`. Requires `Idempotency-Key`. Requires `appointments:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: createAppointment security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppointmentCreate' example: service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 client_name: Giulia client_surname: Bianchi start_at: '2026-10-08T09:00:00Z' end_at: '2026-10-08T09:30:00Z' quantity: 1 notes: First visit responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Appointment' example: *id016 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter or body field is invalid (`invalid_parameter`), a quantity outside the service's range included; the booking cannot be made at any time (`service_inactive`, `location_inactive`, `party_too_large`, or another `400` booking code); `Idempotency-Key` is missing (`idempotency_key_required`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: service_inactive message: That service does not exist or is not bookable. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: The supplied service does not exist in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such service. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The booking was refused: the time cannot be booked (`slot_unavailable`, `capacity_exhausted`, `service_exclusion`, `closed_day`, `in_the_past`, `outside_hours`): check `GET /v1/availability` and try another time; `booking_refused` for a refusal with no code of its own. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: slot_unavailable message: That time is no longer available. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/appointments'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ booking-crm-1042\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"service_id\":\"45c470b7-592a-42cd-8ce8-5d7a0a497d26\",\"client_name\"\ :\"Giulia\",\"client_surname\":\"Bianchi\",\"start_at\":\"2026-10-08T09:00:00Z\"\ ,\"end_at\":\"2026-10-08T09:30:00Z\",\"quantity\":1,\"notes\":\"First visit\"\ }'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nappointment = talki.appointments.create(\n\ \ body={\n \"service_id\": \"45c470b7-592a-42cd-8ce8-5d7a0a497d26\"\ ,\n \"client_name\": \"Giulia\",\n \"client_surname\": \"\ Bianchi\",\n \"start_at\": \"2026-10-08T09:00:00Z\",\n \"\ end_at\": \"2026-10-08T09:30:00Z\",\n \"quantity\": 1,\n \"\ notes\": \"First visit\",\n },\n idempotency_key=\"booking-crm-1042\"\ ,\n)\nprint(appointment)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst appointment = await talki.appointments.create({\n body: {\n \ \ service_id: \"45c470b7-592a-42cd-8ce8-5d7a0a497d26\",\n client_name:\ \ \"Giulia\",\n client_surname: \"Bianchi\",\n start_at: \"2026-10-08T09:00:00Z\"\ ,\n end_at: \"2026-10-08T09:30:00Z\",\n quantity: 1,\n notes: \"\ First visit\",\n },\n idempotencyKey: \"booking-crm-1042\",\n});\nconsole.log(appointment);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: booking-crm-1042 /v1/appointments/{appointment_id}: get: tags: - Appointments summary: Retrieve an appointment operationId: getAppointment security: - ApiKeyAuth: [] parameters: - name: appointment_id in: path required: true schema: type: string title: Appointment Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Appointment' example: *id016 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No appointment with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such appointment. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one active or cancelled appointment belonging to the account. Requires `appointments:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/appointments/a3fe45ee-572f-4677-b1dd-f36c21bb47de'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() appointment = talki.appointments.get("a3fe45ee-572f-4677-b1dd-f36c21bb47de") print(appointment)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const appointment = await talki.appointments.get("a3fe45ee-572f-4677-b1dd-f36c21bb47de"); console.log(appointment);' patch: tags: - Appointments summary: Update an appointment description: Move or rename a booking while keeping its ID. A move is refused with `service_deleted` when a service of the booking has been deleted and the move would make that service's part of the booking end in the future, and with `location_inactive` when the booking's location is switched off; such a booking can still be renamed. Requires `Idempotency-Key`. Requires `appointments:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: rescheduleAppointment security: - ApiKeyAuth: [] parameters: - name: appointment_id in: path required: true schema: type: string title: Appointment Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: reschedule-crm-1042 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppointmentReschedule' example: start_at: '2026-10-08T10:00:00Z' end_at: '2026-10-08T10:30:00Z' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Appointment' example: *id016 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter or body field is invalid (`invalid_parameter`); the booking cannot be made at any time (`service_deleted`, `location_inactive`, or another `400` booking code); `Idempotency-Key` is missing (`idempotency_key_required`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: service_deleted message: A service of this booking has been deleted, so the booking cannot be restored or moved to a time still to come. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No appointment with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such appointment. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The appointment is cancelled (`appointment_cancelled`): restore it first. Or the time cannot be booked (`slot_unavailable`, `capacity_exhausted`, `service_exclusion`, `closed_day`, `in_the_past`, `outside_hours`): check `GET /v1/availability` and try another time; `booking_refused` for a refusal with no code of its own. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: slot_unavailable message: That time is no longer available. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/appointments/a3fe45ee-572f-4677-b1dd-f36c21bb47de'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ reschedule-crm-1042\" \\\n -H \"Content-Type: application/json\" \\\n\ \ --data '{\"start_at\":\"2026-10-08T10:00:00Z\",\"end_at\":\"2026-10-08T10:30:00Z\"\ }'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nappointment = talki.appointments.reschedule(\n\ \ \"a3fe45ee-572f-4677-b1dd-f36c21bb47de\",\n body={\"start_at\":\ \ \"2026-10-08T10:00:00Z\", \"end_at\": \"2026-10-08T10:30:00Z\"},\n \ \ idempotency_key=\"reschedule-crm-1042\",\n)\nprint(appointment)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst appointment = await talki.appointments.reschedule(\n \"a3fe45ee-572f-4677-b1dd-f36c21bb47de\"\ ,\n {\n body: { start_at: \"2026-10-08T10:00:00Z\", end_at: \"2026-10-08T10:30:00Z\"\ \ },\n idempotencyKey: \"reschedule-crm-1042\",\n },\n);\nconsole.log(appointment);" delete: tags: - Appointments summary: Cancel an appointment description: Mark a booking cancelled without deleting it. Requires `Idempotency-Key`. Requires `appointments:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: cancelAppointment security: - ApiKeyAuth: [] parameters: - name: appointment_id in: path required: true schema: type: string title: Appointment Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: cancel-crm-1042 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No appointment with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such appointment. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The appointment is already cancelled (`appointment_cancelled`). Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: appointment_cancelled message: This appointment is already cancelled. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/appointments/a3fe45ee-572f-4677-b1dd-f36c21bb47de'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ cancel-crm-1042\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.appointments.cancel(\n\ \ \"a3fe45ee-572f-4677-b1dd-f36c21bb47de\",\n idempotency_key=\"cancel-crm-1042\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.appointments.cancel(\"a3fe45ee-572f-4677-b1dd-f36c21bb47de\"\ , {\n idempotencyKey: \"cancel-crm-1042\",\n});" /v1/contacts: get: tags: - Contacts summary: List contact changes operationId: listContacts security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of contacts to return. default: 50 title: Limit description: Maximum number of contacts to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading the whole address book. Not interchangeable with another endpoint''s cursor.' title: Cursor description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading the whole address book. Not interchangeable with another endpoint''s cursor.' - name: phone in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the contact with this number: E.164, or a national number read as Italian. Makes the list a search: see `tag_id`.' title: Phone description: 'Only the contact with this number: E.164, or a national number read as Italian. Makes the list a search: see `tag_id`.' - name: tag_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only contacts with this tag (`Tag.id`). With it or `phone` the list is a search, not the change feed: newest contact first, `next_cursor` null on the last page, and a cursor works only in the mode that issued it. Resume a sync from the unfiltered feed.' title: Tag Id description: 'Only contacts with this tag (`Tag.id`). With it or `phone` the list is a search, not the change feed: newest contact first, `next_cursor` null on the last page, and a cursor works only in the mode that issued it. Resume a sync from the unfiltered feed.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactList' example: data: - &id017 id: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d phone_number: '+393331234567' first_name: Giulia last_name: Bianchi display_name: Giulia Bianchi notes: Prefers morning appointments last_call_at: '2026-09-15T09:14:31Z' call_count: 3 created_at: '2026-08-20T12:00:00Z' updated_at: '2026-09-15T09:18:03Z' next_cursor: s1.sample has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`phone` is not a phone number, or another parameter is invalid (`invalid_parameter`). Or the `cursor` is not one this mode issued: altered, from another feed, or from the other mode, since a search answers with a list cursor and the feed with a change-feed cursor (`invalid_cursor`). `Talki-Version` may also name an unsupported version (`unsupported_version`).' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: '`phone` must be a phone number, E.164 or national.' request_id: req_7f24a2f8c6b64e699901563a458b5031 description: 'Walk the curated-contact change feed in commit order. With `phone` or `tag_id`, find contacts instead: newest first, not resumable as a sync. Requires `contacts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/contacts?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.contacts.list(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.contacts.list({ limit: 10 }); console.log(page.data);' put: tags: - Contacts summary: Upsert a contact description: Create or update a trusted contact by phone number or external reference. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: upsertContact security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactUpsert' example: phone_number: '+393331234567' first_name: Giulia last_name: Bianchi external_id: crm-contact-42 system: acme-crm responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Contact' example: *id017 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PUT 'https://api.talki.it/v1/contacts' \\\ \n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ contact-crm-42\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"phone_number\":\"+393331234567\",\"first_name\":\"Giulia\",\"last_name\"\ :\"Bianchi\",\"external_id\":\"crm-contact-42\",\"system\":\"acme-crm\"\ }'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ncontact = talki.contacts.upsert(\n\ \ body={\n \"phone_number\": \"+393331234567\",\n \"first_name\"\ : \"Giulia\",\n \"last_name\": \"Bianchi\",\n \"external_id\"\ : \"crm-contact-42\",\n \"system\": \"acme-crm\",\n },\n idempotency_key=\"\ contact-crm-42\",\n)\nprint(contact)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst contact = await talki.contacts.upsert({\n body: {\n phone_number:\ \ \"+393331234567\",\n first_name: \"Giulia\",\n last_name: \"Bianchi\"\ ,\n external_id: \"crm-contact-42\",\n system: \"acme-crm\",\n },\n\ \ idempotencyKey: \"contact-crm-42\",\n});\nconsole.log(contact);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: contact-crm-42 /v1/contacts/{contact_id}: get: tags: - Contacts summary: Retrieve a contact operationId: getContact security: - ApiKeyAuth: [] parameters: - name: contact_id in: path required: true schema: type: string title: Contact Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Contact' example: *id017 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No contact with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such contact. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one curated contact belonging to the account. Requires `contacts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/contacts/8fbb25f2-4f3b-4496-8aea-f0fc66de512d'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() contact = talki.contacts.get("8fbb25f2-4f3b-4496-8aea-f0fc66de512d") print(contact)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const contact = await talki.contacts.get("8fbb25f2-4f3b-4496-8aea-f0fc66de512d"); console.log(contact);' delete: tags: - Contacts summary: Delete a contact description: Delete a contact with its tags and `external_id`. Calls and appointments are kept. If the number is in an address book the owner connected, its next call creates the contact again under a new `id`. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: deleteContact security: - ApiKeyAuth: [] parameters: - name: contact_id in: path required: true schema: type: string title: Contact Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: contact-delete-crm-42 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No contact with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such contact. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/contacts/8fbb25f2-4f3b-4496-8aea-f0fc66de512d'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ contact-delete-crm-42\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.contacts.delete(\n\ \ \"8fbb25f2-4f3b-4496-8aea-f0fc66de512d\",\n idempotency_key=\"contact-delete-crm-42\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.contacts.delete(\"8fbb25f2-4f3b-4496-8aea-f0fc66de512d\",\ \ {\n idempotencyKey: \"contact-delete-crm-42\",\n});" /v1/services: get: tags: - Services summary: List service changes description: Walk the service-catalogue change feed in commit order. Walking from no cursor until `has_more` is false reads every current service. Requires `services:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listServices security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of services to return. default: 50 title: Limit description: Maximum number of services to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading the whole catalogue. Not interchangeable with another endpoint''s cursor.' title: Cursor description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading the whole catalogue. Not interchangeable with another endpoint''s cursor.' - name: is_active in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Restrict to services that are switched on (`true`) or off (`false`). Omit to get both — which is what an incremental sync needs, since switching a service off is a change you must see. Use this only for a point-in-time snapshot. title: Is Active description: Restrict to services that are switched on (`true`) or off (`false`). Omit to get both — which is what an incremental sync needs, since switching a service off is a change you must see. Use this only for a point-in-time snapshot. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ServiceList' example: data: - &id018 id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Haircut description: Wash and cut price: 30€ duration_minutes: 30 booking_mode: duration range_unit: null min_stay: null max_stay: null checkin_time: null checkout_time: null asks_quantity: false quantity_label: null min_quantity: 1 max_quantity: null is_active: true created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' next_cursor: s1.sample has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/services?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.services.list(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.services.list({ limit: 10 }); console.log(page.data);' post: tags: - Services summary: Create a service description: Create a service with a fixed duration, bookable at once, at the location `location_id` names, the main location without it. Send at most one of `initial_capacity` or `resource_ids` (resources of the same location); with neither, it draws on that location's default resource. Requires `Idempotency-Key`. Requires `services:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 20 creations per minute shared by the services, resources, tags and caller rules you create. operationId: createService security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location to create the service at, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location to create the service at, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: service-create-colour requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ServiceCreate' example: name: Colour description: Full colour with blow-dry price: from 60€ duration_minutes: 90 initial_capacity: 2 responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Service' example: id: 0d6b3f81-2c4e-4a97-b5d0-8e1f7a3c9b26 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Colour description: Full colour with blow-dry price: from 60€ duration_minutes: 90 booking_mode: duration range_unit: null min_stay: null max_stay: null checkin_time: null checkout_time: null asks_quantity: false quantity_label: null min_quantity: 1 max_quantity: null is_active: true created_at: '2026-09-30T08:15:02Z' updated_at: '2026-09-30T08:15:02Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A body field is invalid, both `initial_capacity` and `resource_ids` were sent, neither was and the location has no default resource yet, or a resource in `resource_ids` is at another location (`invalid_parameter`); a booking of this service would not fit a resource in `resource_ids`, or the default resource (`resource_too_small`); `Idempotency-Key` is missing (`idempotency_key_required`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_too_small message: A booking of this service would not fit one of the resources in `resource_ids`. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: A resource in `resource_ids`, or the location `location_id` names, does not exist in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such resource. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/services'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ service-create-colour\" \\\n -H \"Content-Type: application/json\" \\\ \n --data '{\"name\":\"Colour\",\"description\":\"Full colour with blow-dry\"\ ,\"price\":\"from 60€\",\"duration_minutes\":90,\"initial_capacity\":2}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nservice = talki.services.create(\n\ \ body={\n \"name\": \"Colour\",\n \"description\": \"\ Full colour with blow-dry\",\n \"price\": \"from 60€\",\n \ \ \"duration_minutes\": 90,\n \"initial_capacity\": 2,\n },\n\ \ idempotency_key=\"service-create-colour\",\n)\nprint(service)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst service = await talki.services.create({\n body: {\n name: \"\ Colour\",\n description: \"Full colour with blow-dry\",\n price: \"\ from 60€\",\n duration_minutes: 90,\n initial_capacity: 2,\n },\n\ \ idempotencyKey: \"service-create-colour\",\n});\nconsole.log(service);" /v1/services/{service_id}: get: tags: - Services summary: Retrieve a service operationId: getService security: - ApiKeyAuth: [] parameters: - name: service_id in: path required: true schema: type: string title: Service Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Service' example: *id018 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No service with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such service. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one active or inactive service belonging to the account. Requires `services:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/services/45c470b7-592a-42cd-8ce8-5d7a0a497d26'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() service = talki.services.get("45c470b7-592a-42cd-8ce8-5d7a0a497d26") print(service)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const service = await talki.services.get("45c470b7-592a-42cd-8ce8-5d7a0a497d26"); console.log(service);' patch: tags: - Services summary: Update a service description: Update a service's name, description, price, duration or active state; omitted fields stay unchanged. Requires `services:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateService security: - ApiKeyAuth: [] parameters: - name: service_id in: path required: true schema: type: string title: Service Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: service-price-2026-10 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ServiceUpdate' example: price: 30€ responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Service' example: *id018 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No service with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such service. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/services/45c470b7-592a-42cd-8ce8-5d7a0a497d26'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ service-price-2026-10\" \\\n -H \"Content-Type: application/json\" \\\ \n --data '{\"price\":\"30€\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nservice = talki.services.update(\n\ \ \"45c470b7-592a-42cd-8ce8-5d7a0a497d26\",\n body={\"price\": \"\ 30€\"},\n idempotency_key=\"service-price-2026-10\",\n)\nprint(service)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst service = await talki.services.update(\"45c470b7-592a-42cd-8ce8-5d7a0a497d26\"\ , {\n body: { price: \"30€\" },\n idempotencyKey: \"service-price-2026-10\"\ ,\n});\nconsole.log(service);" delete: tags: - Services summary: Delete a service description: 'Delete a service for good. Its own resource (`owner_service_id`) is deleted with it, and it stops drawing on every other resource. Refused with `service_has_upcoming_bookings` while any of its bookings is still to come or under way, even on an inactive service: set `is_active: false` instead, which stops new bookings and keeps those. Past and cancelled bookings stay, with `service.id` null and the service''s name. Sends `service.deleted`, `resource.deleted` for its own resource and `resource.updated` for each other resource it drew on. Requires `services:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: deleteService security: - ApiKeyAuth: [] parameters: - name: service_id in: path required: true schema: type: string title: Service Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: service-delete-1 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No service with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such service. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The service has bookings still to come or under way (`service_has_upcoming_bookings`): set `is_active: false` instead. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: service_has_upcoming_bookings message: 'The service has 3 bookings still to come. Deleting it would leave them without a service, no longer counted against the resources they hold. Set `is_active` to false instead: the service can no longer be booked and its bookings are kept.' request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/services/45c470b7-592a-42cd-8ce8-5d7a0a497d26'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ service-delete-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.services.delete(\n\ \ \"45c470b7-592a-42cd-8ce8-5d7a0a497d26\",\n idempotency_key=\"service-delete-1\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.services.delete(\"45c470b7-592a-42cd-8ce8-5d7a0a497d26\",\ \ {\n idempotencyKey: \"service-delete-1\",\n});" /v1/resources: get: tags: - Resources summary: List resource changes description: Walk the capacity change feed in commit order. A resource moves when its unit classes or service links change too. Walking from no cursor until `has_more` is false reads every current resource. Requires `resources:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listResources security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of resources to return. default: 50 title: Limit description: Maximum number of resources to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading the whole inventory. Not interchangeable with another endpoint''s cursor.' title: Cursor description: 'Opaque position in the change feed, from a previous response''s `next_cursor`. Omit to start from the beginning. Store the last one you received: it is how you resume a sync without re-reading the whole inventory. Not interchangeable with another endpoint''s cursor.' - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ResourceList' example: data: - &id019 id: b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Dining room mode: units capacity: 4 max_party_size: 8 combine_across_classes: false unit_classes: - id: 1f2b9c07-3d64-4a1e-8f95-2b7c6d0e4a31 name: Four-tops size: 4 count: 6 combinable: true combine_max: 2 services: - service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 rate: 1 owner_service_id: null is_default: false created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' next_cursor: s1.sample has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/resources?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.resources.list(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.resources.list({ limit: 10 }); console.log(page.data);' post: tags: - Resources summary: Create a resource description: Create a `shared` resource at the location `location_id` names, the main location without it, optionally drawn on by existing services of that location. Requires `Idempotency-Key`. Requires `resources:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 20 creations per minute shared by the services, resources, tags and caller rules you create. operationId: createResource security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location to create the resource at, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location to create the resource at, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: resource-create-basins requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResourceCreate' example: name: Wash basins capacity: 3 service_ids: - 45c470b7-592a-42cd-8ce8-5d7a0a497d26 responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Resource' example: id: 7a4e2d19-6f3b-4c85-9e02-b1d8c5a7f364 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Wash basins mode: shared capacity: 3 max_party_size: 3 combine_across_classes: false unit_classes: &id020 [] services: - service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 rate: 1 owner_service_id: null is_default: false created_at: '2026-09-30T08:16:40Z' updated_at: '2026-09-30T08:16:40Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A body field is invalid, or a service in `service_ids` is booked by the day or night, has no duration or is at another location (`invalid_parameter`); a linked service can request more units than `capacity` allows (`capacity_below_service_requirement`); `Idempotency-Key` is missing (`idempotency_key_required`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: capacity_below_service_requirement message: A service in `service_ids` can request more units than this capacity allows. Raise the capacity, or lower the service's quantity range in Talki first. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: A service in `service_ids`, or the location `location_id` names, does not exist in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such service. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/resources'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ resource-create-basins\" \\\n -H \"Content-Type: application/json\" \\\ \n --data '{\"name\":\"Wash basins\",\"capacity\":3,\"service_ids\":[\"\ 45c470b7-592a-42cd-8ce8-5d7a0a497d26\"]}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nresource = talki.resources.create(\n\ \ body={\n \"name\": \"Wash basins\",\n \"capacity\": 3,\n\ \ \"service_ids\": [\"45c470b7-592a-42cd-8ce8-5d7a0a497d26\"],\n\ \ },\n idempotency_key=\"resource-create-basins\",\n)\nprint(resource)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst resource = await talki.resources.create({\n body: {\n name:\ \ \"Wash basins\",\n capacity: 3,\n service_ids: [\"45c470b7-592a-42cd-8ce8-5d7a0a497d26\"\ ],\n },\n idempotencyKey: \"resource-create-basins\",\n});\nconsole.log(resource);" /v1/resources/{resource_id}: get: tags: - Resources summary: Retrieve a resource operationId: getResource security: - ApiKeyAuth: [] parameters: - name: resource_id in: path required: true schema: type: string title: Resource Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Resource' example: *id019 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No resource with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such resource. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one resource belonging to the account, with its unit classes and service links. Requires `resources:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/resources/b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() resource = talki.resources.get("b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52") print(resource)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const resource = await talki.resources.get("b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52"); console.log(resource);' patch: tags: - Resources summary: Update a resource description: Rename a resource or set the capacity of a `shared` one. Refused when bookings already exceed it. Requires `resources:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateResource security: - ApiKeyAuth: [] parameters: - name: resource_id in: path required: true schema: type: string title: Resource Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: capacity-2026-10 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResourceUpdate' example: capacity: 24 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Resource' example: id: c47a1f60-8b2d-4e59-9d31-05a6c8b4f7e2 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Styling chairs mode: shared capacity: 24 max_party_size: 24 combine_across_classes: false unit_classes: *id020 services: - service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 rate: 1 owner_service_id: null is_default: false created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-16T11:05:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No resource with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such resource. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: Bookings already on the calendar need more of this resource than the requested capacity, or the idempotency key was reused for a different request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: capacity_below_committed message: Bookings already on the calendar use 26 units of this resource at once (from 2026-10-08T19:30:00Z), which is more than the requested capacity of 24. Existing bookings are never cancelled by a capacity change, so this would leave the resource over-committed. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/resources/b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ capacity-2026-10\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"capacity\":24}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nresource = talki.resources.update(\n\ \ \"b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52\",\n body={\"capacity\":\ \ 24},\n idempotency_key=\"capacity-2026-10\",\n)\nprint(resource)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst resource = await talki.resources.update(\"b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52\"\ , {\n body: { capacity: 24 },\n idempotencyKey: \"capacity-2026-10\",\n\ });\nconsole.log(resource);" delete: tags: - Resources summary: Delete a resource description: 'Delete a resource for good, with its unit classes and service links. Refused with `resource_is_default` for the default resource (`is_default`), and with `resource_required_by_service` when it is the only resource of an active service, or of a service booked by the day or night even while inactive: link that service to another resource first. Bookings are never cancelled; one that held a unit of this resource keeps its time and loses the unit. Sends `resource.deleted` with the resource as it was. Requires `resources:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: deleteResource security: - ApiKeyAuth: [] parameters: - name: resource_id in: path required: true schema: type: string title: Resource Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: resource-delete-1 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No resource with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such resource. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The resource is the default one (`resource_is_default`), or a service draws on no other resource (`resource_required_by_service`): the message lists their IDs. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: resource_required_by_service message: 'These services draw on no other resource and could not be booked without this one: 45c470b7-592a-42cd-8ce8-5d7a0a497d26. Link them to another resource first. A day_range service counts even while inactive: switched back on, it would have nothing to book.' request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/resources/b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ resource-delete-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.resources.delete(\n\ \ \"b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52\",\n idempotency_key=\"resource-delete-1\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.resources.delete(\"b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52\"\ , {\n idempotencyKey: \"resource-delete-1\",\n});" /v1/unresolved_requests: get: tags: - Unresolved requests summary: List unresolved-request changes operationId: listUnresolvedRequests security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of requests to return. default: 50 title: Limit description: Maximum number of requests to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque position in the change feed, from a previous response's `next_cursor`. Omit to start from the beginning. Not interchangeable with another endpoint's cursor. title: Cursor description: Opaque position in the change feed, from a previous response's `next_cursor`. Omit to start from the beginning. Not interchangeable with another endpoint's cursor. - name: status in: query required: false schema: anyOf: - $ref: '#/components/schemas/UnresolvedRequestStatus' - type: 'null' description: Restrict to `open`, `resolved` or `dismissed`. Omit to get all of them — which is what an incremental sync needs, since a request being closed is the change you most need to see. Use this only for a point-in-time snapshot of the open list. title: Status description: Restrict to `open`, `resolved` or `dismissed`. Omit to get all of them — which is what an incremental sync needs, since a request being closed is the change you most need to see. Use this only for a point-in-time snapshot of the open list. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`. Allowed on the change feed, because a record never changes location; a cursor is then bound to the location it was issued for, and refused with `invalid_cursor` under another `location_id` or without one.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UnresolvedRequestList' example: data: - &id021 id: 6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 caller_phone: '+393331234567' question: Whether the salon does bridal hair on Sundays. status: open answer: null created_at: '2026-09-15T09:18:03Z' resolved_at: null next_cursor: s1.sample has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Walk the feed of questions the assistant could not answer. A request moves again when it is closed. Requires `unresolved:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/unresolved_requests?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.unresolved_requests.list(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.unresolvedRequests.list({ limit: 10 }); console.log(page.data);' /v1/unresolved_requests/{request_id}: get: tags: - Unresolved requests summary: Retrieve an unresolved request operationId: getUnresolvedRequest security: - ApiKeyAuth: [] parameters: - name: request_id in: path required: true schema: type: string title: Request Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UnresolvedRequest' example: *id021 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No unresolved request with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such unresolved request. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one unresolved request belonging to the account. Requires `unresolved:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/unresolved_requests/6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nunresolved_request\ \ = talki.unresolved_requests.get(\n \"6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13\"\ ,\n)\nprint(unresolved_request)" - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const unresolvedRequest = await talki.unresolvedRequests.get("6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13"); console.log(unresolvedRequest);' patch: tags: - Unresolved requests summary: Update an unresolved request description: Resolve, dismiss or reopen a request, or note the answer given to the caller. Requires `unresolved:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateUnresolvedRequest security: - ApiKeyAuth: [] parameters: - name: request_id in: path required: true schema: type: string title: Request Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: unresolved-resolve-1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnresolvedRequestUpdate' example: status: resolved answer: Yes, on the first Sunday of each month, by appointment. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UnresolvedRequest' example: id: 6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 caller_phone: '+393331234567' question: Whether the salon does bridal hair on Sundays. status: resolved answer: Yes, on the first Sunday of each month, by appointment. created_at: '2026-09-15T09:18:03Z' resolved_at: '2026-09-15T11:40:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No unresolved request with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such unresolved request. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/unresolved_requests/6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ unresolved-resolve-1\" \\\n -H \"Content-Type: application/json\" \\\n\ \ --data '{\"status\":\"resolved\",\"answer\":\"Yes, on the first Sunday\ \ of each month, by appointment.\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nunresolved_request\ \ = talki.unresolved_requests.update(\n \"6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13\"\ ,\n body={\n \"status\": \"resolved\",\n \"answer\": \"\ Yes, on the first Sunday of each month, by appointment.\",\n },\n \ \ idempotency_key=\"unresolved-resolve-1\",\n)\nprint(unresolved_request)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst unresolvedRequest = await talki.unresolvedRequests.update(\n \"\ 6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13\",\n {\n body: {\n status:\ \ \"resolved\",\n answer: \"Yes, on the first Sunday of each month,\ \ by appointment.\",\n },\n idempotencyKey: \"unresolved-resolve-1\"\ ,\n },\n);\nconsole.log(unresolvedRequest);" /v1/unresolved_requests/{request_id}/teach: post: tags: - Unresolved requests summary: Teach the assistant an answer description: 'Add the general answer to a resolved request''s question to a FAQ note the assistant uses with every caller: the request''s location''s, another location''s, or every location''s (`all`). The business sees, rewords and removes it in Talki, and nothing asks for its approval first, so agree with the business what to teach. The assistant uses the answer shortly after the `202`, once the note is indexed. Teaching the same request again adds another entry. Refused for a request that is not `resolved` (`unresolved_request_not_resolved`), when the note is full (`faq_full`) and when the account''s knowledge storage is full (`payload_too_large`). Requires `Idempotency-Key`. Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: teachUnresolvedRequest security: - ApiKeyAuth: [] parameters: - name: request_id in: path required: true schema: type: string title: Request Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: teach-bridal-sundays requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnresolvedRequestTeach' example: question: Do you do bridal hair on Sundays? answer: Yes, on the first Sunday of each month, by appointment only. responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UnresolvedRequestTeaching' example: unresolved_request_id: 6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 taught_at: '2026-09-15T11:42:10Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No unresolved request with this ID exists in the authenticated account, or `location_id` names no location of it. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such unresolved request. request_id: req_7f24a2f8c6b64e699901563a458b5031 '413': description: The account's knowledge storage is full for its plan (`payload_too_large`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: payload_too_large message: The account's knowledge storage is full for its plan. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The request is not `resolved` (`unresolved_request_not_resolved`): resolve it first. Or the FAQ note has no room left (`faq_full`): the business tidies it in Talki before more answers are taught. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: unresolved_request_not_resolved message: 'Only a resolved request can be taught from. Resolve it first (`PATCH` with `status: resolved`).' request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/unresolved_requests/6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13/teach'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ teach-bridal-sundays\" \\\n -H \"Content-Type: application/json\" \\\n\ \ --data '{\"question\":\"Do you do bridal hair on Sundays?\",\"answer\"\ :\"Yes, on the first Sunday of each month, by appointment only.\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nunresolved_request_teaching\ \ = talki.unresolved_requests.teach(\n \"6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13\"\ ,\n body={\n \"question\": \"Do you do bridal hair on Sundays?\"\ ,\n \"answer\": \"Yes, on the first Sunday of each month, by appointment\ \ only.\",\n },\n idempotency_key=\"teach-bridal-sundays\",\n)\nprint(unresolved_request_teaching)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst unresolvedRequestTeaching = await talki.unresolvedRequests.teach(\n\ \ \"6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13\",\n {\n body: {\n question:\ \ \"Do you do bridal hair on Sundays?\",\n answer: \"Yes, on the first\ \ Sunday of each month, by appointment only.\",\n },\n idempotencyKey:\ \ \"teach-bridal-sundays\",\n },\n);\nconsole.log(unresolvedRequestTeaching);" /v1/documents: get: tags: - Documents summary: List documents description: 'Return the knowledge-base documents of every location, or of one, newest first, whatever their `status`: an upload is listed from the moment it is received. `document.*` events report every change, `status` included. Requires `knowledge:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' operationId: listDocuments security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of documents to return. default: 50 title: Limit description: Maximum number of documents to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. title: Cursor description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. - name: source in: query required: false schema: anyOf: - type: string enum: - text - file - website - type: 'null' description: Only `text` notes, uploaded `file`s or imported `website`s. title: Source description: Only `text` notes, uploaded `file`s or imported `website`s. - name: enabled in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Only documents switched on (`true`) or off (`false`). title: Enabled description: Only documents switched on (`true`) or off (`false`). - name: faq in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Only the locations' FAQ notes (`true`), or every other document (`false`). title: Faq description: Only the locations' FAQ notes (`true`), or every other document (`false`). - name: copy_group_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the copies sharing this `copy_group_id`. title: Copy Group Id description: Only the copies sharing this `copy_group_id`. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentList' example: data: - &id022 id: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 1 status: ready status_error: null enabled: true faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-28T09:12:40Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/documents?source=text&limit=20'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki from talki.models import ListDocumentsSourceType0 talki = Talki() page = talki.documents.list(source=ListDocumentsSourceType0.TEXT, limit=20) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.documents.list({ source: "text", limit: 20 }); console.log(page.data);' post: tags: - Documents summary: Create a document operationId: createDocument security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location the document is for, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location the document is for, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: faq-parking responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Document' example: id: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 0 status: processing status_error: null enabled: true faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-28T09:12:40Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id`, or a location in `location_ids`, names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '413': description: The file is over the plan's upload size, a note is over 100 KB, or the account's knowledge storage is full for its plan (`payload_too_large`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: payload_too_large message: The account's knowledge storage is full for its plan. request_id: req_7f24a2f8c6b64e699901563a458b5031 '415': description: The file is not a PDF, DOCX, XLSX, TXT or CSV file, its content does not match its type, or the body is neither `application/json` nor `multipart/form-data` (`unsupported_file_type`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_file_type message: The file must be a PDF, DOCX, XLSX, TXT or CSV file (.pdf, .docx, .xlsx, .txt, .csv). request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The website is already imported at one of the locations (`conflict`): import it again with `PUT`. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: conflict message: 'This site is already imported at that location, as document 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36: import it again with `PUT /v1/documents/{document_id}`.' request_id: req_7f24a2f8c6b64e699901563a458b5031 requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/DocumentCreate' - $ref: '#/components/schemas/DocumentSiteCreate' example: title: Is there parking? body: 'Yes: free parking behind the salon, entrance from Via Roma.' multipart/form-data: schema: $ref: '#/components/schemas/DocumentUpload' description: 'Add a text note (`application/json`: `title`, `body`), import a website (`application/json`: `source: "website"`, `url`, optionally `pages`) or upload a file (`multipart/form-data`: `file`) to the knowledge base of the location `location_id` names, the main location''s when omitted. A site already imported at one of the locations is refused (`conflict`): import it again with `PUT`. `location_ids` makes a copy at each of those locations too, sharing `copy_group_id`. Answers `202` with the document, `processing`: the assistant uses it once `document.updated` reports it `ready`, or `failed` with `status_error`. The plan''s limits apply as in Talki: file size (`payload_too_large`), file type (`unsupported_file_type`), pages per site (`invalid_parameter`) and the account''s knowledge storage (`payload_too_large`, or a site `failed` with `status_error`). A JSON field the note or the website does not take is refused (`invalid_parameter`). Requires `Idempotency-Key`. Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 60 document writes per minute, shared by creating, replacing and updating documents and discovering a site''s pages.' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/documents'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ faq-parking\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"title\":\"Is there parking?\",\"body\":\"Yes: free parking behind\ \ the salon, entrance from Via Roma.\"}'" - lang: python label: Python source: "from talki import Talki\nfrom talki.models import DocumentCreate\n\ \ntalki = Talki()\n\ndocument = talki.documents.create(\n body=DocumentCreate(\n\ \ title=\"Is there parking?\",\n body=\"Yes: free parking\ \ behind the salon, entrance from Via Roma.\",\n ),\n idempotency_key=\"\ faq-parking\",\n)\nprint(document)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst document = await talki.documents.create({\n body: {\n title:\ \ \"Is there parking?\",\n body: \"Yes: free parking behind the salon,\ \ entrance from Via Roma.\",\n },\n idempotencyKey: \"faq-parking\",\n\ });\nconsole.log(document);" /v1/documents/{document_id}: get: tags: - Documents summary: Retrieve a document operationId: getDocument security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Document' example: *id022 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return one document of the account, with its indexing `status`. Requires `knowledge:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() document = talki.documents.get("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36") print(document)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const document = await talki.documents.get("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36"); console.log(document);' put: tags: - Documents summary: Replace a document operationId: replaceDocument security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: also in: query required: false schema: anyOf: - type: string enum: - copies - type: 'null' description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' title: Also description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: faq-parking-v2 responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Document' example: id: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 1 status: processing status_error: null enabled: true faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-29T15:03:11Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document. request_id: req_7f24a2f8c6b64e699901563a458b5031 '413': description: The file is over the plan's upload size, a note is over 100 KB, or the account's knowledge storage is full for its plan (`payload_too_large`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: payload_too_large message: The account's knowledge storage is full for its plan. request_id: req_7f24a2f8c6b64e699901563a458b5031 '415': description: The file is not a PDF, DOCX, XLSX, TXT or CSV file, its content does not match its type, or the body is neither `application/json` nor `multipart/form-data` (`unsupported_file_type`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_file_type message: The file must be a PDF, DOCX, XLSX, TXT or CSV file (.pdf, .docx, .xlsx, .txt, .csv). request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'A file''s first upload is still `processing`, or its new version has been read and is about to replace the previous one; or a website is being imported (`document_not_ready`), for the document or, with `also=copies`, a copy: retry once it is `ready` or `failed`, and again shortly if a file is still refused, or without `also=copies` when a copy holds it up. Or an older document holds the same site at the website''s location (`conflict`): import that one again, or delete one of the two. Or another request changed the document''s copies at the same time (`request_conflict`): retry. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key. `request_conflict` and `document_not_ready` clear by themselves and are not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: document_not_ready message: The last file sent to this document is not in place yet. Retry shortly. request_id: req_7f24a2f8c6b64e699901563a458b5031 requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/DocumentReplace' - $ref: '#/components/schemas/DocumentSiteReplace' example: body: 'Yes: free parking behind the salon, entrance from Via Roma, 8:00 to 20:00.' multipart/form-data: schema: $ref: '#/components/schemas/DocumentFileReplace' description: 'Replace a note''s text (`application/json`: `body`, optionally `title`) or a file (`multipart/form-data`: `file`), keeping the document''s id. It turns `processing` and keeps answering with its previous content until the new one is `ready`; a new file''s name and size are the document''s from then. A website is imported again (`application/json`: `pages`, or omit it to read again the pages it holds). A note can be replaced at any time, and a file again while its new version is still being read: the newer one takes its place. Refused (`document_not_ready`) for a file whose first upload is still `processing` or whose new version has been read and is about to replace the previous one, and for a website being imported; and (`conflict`) for a website whose location holds an older document of the same site. With `also=copies`, its copies at other locations get the same content, and the `document_not_ready` refusals apply to each copy. The JSON body is read as the document''s kind: a field that kind does not take, such as `source`, or a note''s `body` sent to a website, is refused (`invalid_parameter`) and nothing changes. Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 60 document writes per minute, shared by creating, replacing and updating documents and discovering a site''s pages.' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PUT 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36?also=copies'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ faq-parking-v2\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"body\":\"Yes: free parking behind the salon, entrance from Via Roma,\ \ 8:00 to 20:00.\"}'" - lang: python label: Python source: "from talki import Talki\nfrom talki.models import DocumentAlso, DocumentReplace\n\ \ntalki = Talki()\n\ndocument = talki.documents.replace(\n \"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ ,\n also=DocumentAlso.COPIES,\n body=DocumentReplace(\n body=\"\ Yes: free parking behind the salon, entrance from Via Roma, 8:00 to 20:00.\"\ ,\n ),\n idempotency_key=\"faq-parking-v2\",\n)\nprint(document)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst document = await talki.documents.replace(\"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ , {\n also: \"copies\",\n body: {\n body: \"Yes: free parking behind\ \ the salon, entrance from Via Roma, 8:00 to 20:00.\",\n },\n idempotencyKey:\ \ \"faq-parking-v2\",\n});\nconsole.log(document);" patch: tags: - Documents summary: Update a document operationId: updateDocument security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: also in: query required: false schema: anyOf: - type: string enum: - copies - type: 'null' description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' title: Also description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: faq-parking-off requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DocumentUpdate' example: enabled: false responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Document' example: id: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 1 status: ready status_error: null enabled: false faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-28T09:12:40Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'A file''s new title was sent while it is `processing`, or with `also=copies` while a copy''s file is (`document_not_ready`): retry once it is `ready` or `failed`, or rename without `also=copies`. Or another request changed the document''s copies at the same time (`request_conflict`): retry. Or the idempotency key was reused for a different request. `request_conflict` and `document_not_ready` clear by themselves and are not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: document_not_ready message: The file of this document is still being processed. Rename it once its `status` is no longer `processing`. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: 'Rename a document, or switch it off (`enabled: false`) so the assistant stops using it while it is kept, and on again. A note''s new title is indexed again, as its text is. A file''s title cannot change while it is `processing` (`document_not_ready`). A website''s title is its address and cannot change. With `also=copies`, its copies at other locations change too, and a rename is refused the same way (`document_not_ready`) while a copy''s file is `processing`. Any other field is refused (`invalid_parameter`). A request that changes nothing sends no `document.updated`. Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 60 document writes per minute, shared by creating, replacing and updating documents and discovering a site''s pages.' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ faq-parking-off\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"enabled\":false}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ndocument = talki.documents.update(\n\ \ \"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\",\n body={\"enabled\": False},\n\ \ idempotency_key=\"faq-parking-off\",\n)\nprint(document)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst document = await talki.documents.update(\"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ , {\n body: { enabled: false },\n idempotencyKey: \"faq-parking-off\"\ ,\n});\nconsole.log(document);" delete: tags: - Documents summary: Delete a document operationId: deleteDocument security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: also in: query required: false schema: anyOf: - type: string enum: - copies - type: 'null' description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' title: Also description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: faq-parking-delete responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'Another request changed the document''s copies at the same time (`request_conflict`): retry. Or the idempotency key was reused for a different request. `request_conflict` clears by itself and is not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: request_conflict message: Another request changed this document's copies at the same time; retry. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: 'Delete a document for good; the assistant stops using it at once. A location''s FAQ note can be deleted too: the next answer taught there starts a new one. With `also=copies`, its copies at other locations go too; without it they stay. Sends `document.deleted`. Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36?also=copies'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ faq-parking-delete\"" - lang: python label: Python source: "from talki import Talki\nfrom talki.models import DocumentAlso\n\n\ talki = Talki()\n\ntalki.documents.delete(\n \"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ ,\n also=DocumentAlso.COPIES,\n idempotency_key=\"faq-parking-delete\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.documents.delete(\"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ , {\n also: \"copies\",\n idempotencyKey: \"faq-parking-delete\",\n});" /v1/documents/{document_id}/text: get: tags: - Documents summary: Retrieve a document's text description: 'Return a note''s text as last written, even while it is `processing`, or the text Talki read from a file or a website, as the assistant searches it: empty until the file or website is first `ready`. The uploaded file itself is `GET /v1/documents/{document_id}/file`. Requires `knowledge:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' operationId: getDocumentText security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentText' example: document_id: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 text: 'Yes: free parking behind the salon, entrance from Via Roma.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document. request_id: req_7f24a2f8c6b64e699901563a458b5031 '503': description: The text of a file or a website cannot be read right now (`api_error`). Retry later. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: api_error message: The knowledge index is temporarily unavailable. Retry later. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36/text'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() document_text = talki.documents.get_text("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36") print(document_text)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const documentText = await talki.documents.getText("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36"); console.log(documentText);' /v1/documents/{document_id}/pages: get: tags: - Documents summary: List a website's pages description: Return every page of an imported website as its last import read them, with whether each was read (`status`). Only a website has pages; any other document is refused (`invalid_parameter`). Requires `knowledge:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listDocumentPages security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentPageList' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: The document is not a website, the only kind with pages (`invalid_parameter`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: 'This document is a text note: only a website has pages.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36/pages'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() document_page_list = talki.documents.list_pages("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36") print(document_page_list)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const documentPageList = await talki.documents.listPages("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36"); console.log(documentPageList);' /v1/documents/{document_id}/file: get: tags: - Documents summary: Download a document's file description: 'Return the uploaded file as it was received, with its type and name, when the document''s `file_available` is true: shortly after the file is first `ready`, later for a copy at another location. A note, a website, a file whose first upload is not `ready` yet or `failed`, and a file Talki did not keep have none (`resource_not_found`). A file being replaced returns its previous version until the new one has been read, then its new version shortly after it is `ready`. Requires `knowledge:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' operationId: getDocumentFile security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: The file, with its own `Content-Type` (PDF, DOCX, XLSX, plain text or CSV) and its name in `Content-Disposition`. content: application/octet-stream: schema: type: string format: binary headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: 'No document with this ID exists in the authenticated account, or it has no file to return: `file_available` is false (`resource_not_found`).' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: 'This document has no file to return: it is a note or a website, or its file is not kept, or not yet (`file_available` is false).' request_id: req_7f24a2f8c6b64e699901563a458b5031 '503': description: The file cannot be read right now (`api_error`). Retry later. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: api_error message: The file cannot be read right now. Retry later. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36/file'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n --output listino.pdf" - lang: python label: Python source: 'from pathlib import Path from talki import Talki talki = Talki() file = talki.documents.get_file("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36") Path("listino.pdf").write_bytes(file.payload.read())' - lang: ts label: TypeScript source: 'import { writeFile } from "node:fs/promises"; import { Talki } from "@hubtec/talki"; const talki = new Talki(); const file = await talki.documents.getFile("5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36"); await writeFile("listino.pdf", new Uint8Array(await file.arrayBuffer()));' /v1/voices: get: tags: - Voices summary: List voices operationId: listVoices responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VoiceList' example: data: - id: Charon name: Charon gender: male preview_url: /v1/voices/Charon/preview - id: Achird name: Achird gender: male preview_url: /v1/voices/Achird/preview - id: Iapetus name: Iapetus gender: male preview_url: /v1/voices/Iapetus/preview - id: Sulafat name: Sulafat gender: female preview_url: /v1/voices/Sulafat/preview - id: Aoede name: Aoede gender: female preview_url: /v1/voices/Aoede/preview - id: Leda name: Leda gender: female preview_url: /v1/voices/Leda/preview next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] description: Return every voice the assistant can speak with. The account's `voice` is one of these IDs. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/voices' \\\n\ \ -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() voice_list = talki.voices.list() print(voice_list)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const voiceList = await talki.voices.list(); console.log(voiceList);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 /v1/voices/{voice_id}/preview: get: tags: - Voices summary: Retrieve a voice sample operationId: getVoicePreview security: - ApiKeyAuth: [] parameters: - name: voice_id in: path required: true schema: type: string title: Voice Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: A WAV sample. content: audio/wav: schema: type: string format: binary headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No voice with this ID exists; the IDs are listed by `GET /v1/voices`. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such voice. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return a short WAV sample of one voice, the same for every account. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/voices/Sulafat/preview'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n --output voice.wav" - lang: python label: Python source: 'from pathlib import Path from talki import Talki talki = Talki() file = talki.voices.get_preview("Sulafat") Path("voice.wav").write_bytes(file.payload.read())' - lang: ts label: TypeScript source: 'import { writeFile } from "node:fs/promises"; import { Talki } from "@hubtec/talki"; const talki = new Talki(); const file = await talki.voices.getPreview("Sulafat"); await writeFile("voice.wav", new Uint8Array(await file.arrayBuffer()));' /v1/working_hours: get: tags: - Working hours summary: Retrieve working hours description: Return one location's weekly opening hours, the main location's unless `location_id` names another, with an `ETag` to send back as `If-Match`. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: getWorkingHours security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location whose weekly hours to read, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location whose weekly hours to read, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WorkingHours' example: &id024 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 slots: &id023 - days: - 2 - 3 - 4 - 5 start: 09:00 end: '13:00' - days: - 2 - 3 - 4 - 5 start: '14:30' end: '19:00' - days: - 6 start: 09:00 end: '17:00' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' ETag: description: Strong entity tag of the writable content. Send it as `If-Match` on the next write. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/working_hours'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() working_hours = talki.working_hours.get() print(working_hours)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const workingHours = await talki.workingHours.get(); console.log(workingHours);' put: tags: - Working hours summary: Replace working hours description: Replace one location's whole weekly schedule, the main location's unless `location_id` names another. `GET /v1/availability` and the assistant use the new hours at once. Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: replaceWorkingHours security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location whose weekly hours to replace, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location whose weekly hours to replace, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: hours-2026-10 - name: If-Match in: header required: false description: The `ETag` of your last read. If the stored version is a different one, the write is refused with `412 precondition_failed`, unless it asks for exactly what is already stored, so retrying a write that succeeded is safe. `*` always matches; a weak tag (`W/…`) never does. Without it, the write replaces whatever is stored. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkingHoursUpdate' example: slots: *id023 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WorkingHours' example: *id024 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' ETag: description: Strong entity tag of the writable content. Send it as `If-Match` on the next write. Absent on a response replayed from an `Idempotency-Key`; read again for a current one. schema: type: string example: '"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '412': description: '`If-Match` names a version other than the stored one: the settings changed since you read them. Read them again, reapply your change, and retry with the new `ETag`.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: precondition_failed message: This resource changed after the version named in If-Match. Fetch it again, reapply your change, and retry with the new ETag. request_id: req_7f24a2f8c6b64e699901563a458b5031 '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PUT 'https://api.talki.it/v1/working_hours'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ hours-2026-10\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"slots\":[{\"days\":[2,3,4,5],\"start\":\"09:00\",\"end\":\"13:00\"\ },{\"days\":[2,3,4,5],\"start\":\"14:30\",\"end\":\"19:00\"},{\"days\":[6],\"\ start\":\"09:00\",\"end\":\"17:00\"}]}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nworking_hours = talki.working_hours.replace(\n\ \ body={\n \"slots\": [\n {\"days\": [2, 3, 4, 5],\ \ \"start\": \"09:00\", \"end\": \"13:00\"},\n {\"days\": [2,\ \ 3, 4, 5], \"start\": \"14:30\", \"end\": \"19:00\"},\n {\"\ days\": [6], \"start\": \"09:00\", \"end\": \"17:00\"},\n ],\n \ \ },\n idempotency_key=\"hours-2026-10\",\n)\nprint(working_hours)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst workingHours = await talki.workingHours.replace({\n body: {\n \ \ slots: [\n { days: [2, 3, 4, 5], start: \"09:00\", end: \"13:00\"\ \ },\n { days: [2, 3, 4, 5], start: \"14:30\", end: \"19:00\" },\n\ \ { days: [6], start: \"09:00\", end: \"17:00\" },\n ],\n },\n\ \ idempotencyKey: \"hours-2026-10\",\n});\nconsole.log(workingHours);" /v1/closures: get: tags: - Closures summary: List closures description: Return the closures, special openings or both overlapping a range of local days, earliest first, in one page. Closures only unless `kind` says otherwise. With `location_id`, only those that apply at that location, including those of every location. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listClosures security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: First day to list, `YYYY-MM-DD`. Defaults to today. title: From description: First day to list, `YYYY-MM-DD`. Defaults to today. - name: to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: Last day to list, included, `YYYY-MM-DD`. Defaults to a year after `from`. At most 366 days after `from`. title: To description: Last day to list, included, `YYYY-MM-DD`. Defaults to a year after `from`. At most 366 days after `from`. - name: kind in: query required: false schema: enum: - closed - open - all type: string description: '`closed` (the default) for closures, `open` for special openings, `all` for both.' default: closed title: Kind description: '`closed` (the default) for closures, `open` for special openings, `all` for both.' - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only those that apply at this location, an id from `GET /v1/locations`: its own, and those of every location (`location_id` null). Omit for every closure of every location.' title: Location Id description: 'Only those that apply at this location, an id from `GET /v1/locations`: its own, and those of every location (`location_id` null). Omit for every closure of every location.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ClosureList' example: data: - &id025 id: e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35 location_id: null kind: closed all_day: true start_date: '2026-12-24' end_date: '2026-12-26' start_at: '2026-12-23T23:00:00Z' end_at: '2026-12-26T23:00:00Z' reason: Christmas holidays created_at: '2026-09-30T08:12:44Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/closures?from=2026-10-01&to=2026-12-31'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from datetime import date from talki import Talki talki = Talki() closure_list = talki.closures.list(from_=date(2026, 10, 1), to=date(2026, 12, 31)) print(closure_list)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const closureList = await talki.closures.list({ from: "2026-10-01", to: "2026-12-31" }); console.log(closureList);' post: tags: - Closures summary: Create a closure description: 'Close whole days or an exact range, or add hours to one day with a special opening, which must start and end on the same day: at the location `location_id` names, or at every location without it. Appointments already inside a closure are not cancelled. Requires `Idempotency-Key`. Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: createClosure security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ClosureCreate' example: all_day: true start_date: '2026-12-24' end_date: '2026-12-26' reason: Christmas holidays responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Closure' example: *id025 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter or body field is invalid (`invalid_parameter`), including a special opening that does not start and end on the same day in the account's `timezone` (ending at the next midnight is allowed); `Idempotency-Key` is missing (`idempotency_key_required`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: A special opening must start and end on the same day (Europe/Rome time). request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/closures'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ closure-2026-12-24\" \\\n -H \"Content-Type: application/json\" \\\n\ \ --data '{\"all_day\":true,\"start_date\":\"2026-12-24\",\"end_date\"\ :\"2026-12-26\",\"reason\":\"Christmas holidays\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nclosure = talki.closures.create(\n\ \ body={\n \"all_day\": True,\n \"start_date\": \"2026-12-24\"\ ,\n \"end_date\": \"2026-12-26\",\n \"reason\": \"Christmas\ \ holidays\",\n },\n idempotency_key=\"closure-2026-12-24\",\n)\n\ print(closure)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst closure = await talki.closures.create({\n body: {\n all_day:\ \ true,\n start_date: \"2026-12-24\",\n end_date: \"2026-12-26\",\n\ \ reason: \"Christmas holidays\",\n },\n idempotencyKey: \"closure-2026-12-24\"\ ,\n});\nconsole.log(closure);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: closure-2026-12-24 /v1/closures/{closure_id}: patch: tags: - Closures summary: Update a closure description: Change a closure or special opening; omitted fields stay unchanged. To move it, send the whole new window. A special opening must still start and end on the same day. Its `location_id` cannot change. A request that changes nothing sends no `closure.updated`. Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateClosure security: - ApiKeyAuth: [] parameters: - name: closure_id in: path required: true schema: type: string title: Closure Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: closure-reason-2026-12-24 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ClosureUpdate' example: reason: Closed for the Christmas holidays responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Closure' example: id: e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35 location_id: null kind: closed all_day: true start_date: '2026-12-24' end_date: '2026-12-26' start_at: '2026-12-23T23:00:00Z' end_at: '2026-12-26T23:00:00Z' reason: Closed for the Christmas holidays created_at: '2026-09-30T08:12:44Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter or body field is invalid (`invalid_parameter`), including a special opening that does not start and end on the same day in the account's `timezone` (ending at the next midnight is allowed) and a `location_id` other than the closure's own; or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: A special opening must start and end on the same day (Europe/Rome time). request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No closure with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such closure. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/closures/e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ closure-reason-2026-12-24\" \\\n -H \"Content-Type: application/json\"\ \ \\\n --data '{\"reason\":\"Closed for the Christmas holidays\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nclosure = talki.closures.update(\n\ \ \"e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35\",\n body={\"reason\": \"\ Closed for the Christmas holidays\"},\n idempotency_key=\"closure-reason-2026-12-24\"\ ,\n)\nprint(closure)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst closure = await talki.closures.update(\"e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35\"\ , {\n body: { reason: \"Closed for the Christmas holidays\" },\n idempotencyKey:\ \ \"closure-reason-2026-12-24\",\n});\nconsole.log(closure);" delete: tags: - Closures summary: Delete a closure description: Remove a closure or special opening. The time it covered follows the weekly hours again. Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: deleteClosure security: - ApiKeyAuth: [] parameters: - name: closure_id in: path required: true schema: type: string title: Closure Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: closure-delete-2026-12-24 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No closure with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such closure. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/closures/e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ closure-delete-2026-12-24\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.closures.delete(\n\ \ \"e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35\",\n idempotency_key=\"closure-delete-2026-12-24\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.closures.delete(\"e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35\",\ \ {\n idempotencyKey: \"closure-delete-2026-12-24\",\n});" /v1/forwarding_check: get: tags: - Account summary: Retrieve the forwarding check description: Return the state of the latest forwarding check of one location's line, the main location's unless `location_id` names another, and when forwarding was last proven. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: getForwardingCheck security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location whose latest check to read, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location whose latest check to read, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ForwardingCheck' example: location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: verified reason: unconditional verified_at: '2026-10-07T09:30:12Z' last_verified_at: '2026-10-07T09:30:12Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/forwarding_check'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() forwarding_check = talki.account.get_forwarding_check() print(forwarding_check)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const forwardingCheck = await talki.account.getForwardingCheck(); console.log(forwardingCheck);' post: tags: - Account summary: Start a forwarding check description: Ring one location's `forwarding_number` from its `phone_number`, the main location's unless `location_id` names another, then poll `GET /v1/forwarding_check` with the same `location_id`. One check at a time per location; at most 3 an hour per location, and 30 an hour per OAuth app across all the accounts it is installed on and their locations, past which the answer is `429 check_quota_exceeded` with `Retry-After`. Refused in test mode, and for an inactive location (`phone_number_missing`). Requires `account:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: startForwardingCheck security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location whose line to ring, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location whose line to ring, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: forwarding-check-1 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ForwardingCheck' example: location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: pending reason: null verified_at: null last_verified_at: '2026-09-12T16:05:31Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account's trial is suspended (`trial_suspended`), or the credential or account may not make this request (`insufficient_scope`, `plan_upgrade_required`, `account_closed`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: trial_suspended message: This account's trial is suspended, so no check call can be placed. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: 'The location has run 3 checks in the last hour, or the OAuth app 30 across all the accounts it is installed on and their locations (`check_quota_exceeded`): `Retry-After` is the seconds until that hourly count starts again. Or the request rate was exceeded (`rate_limit_exceeded`, `ip_rate_limited`).' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: description: The budget of the window that was exceeded. Absent on `ip_rate_limited` and `check_quota_exceeded`. schema: *id026 X-RateLimit-Remaining: description: Requests left in the window. Absent on `ip_rate_limited` and `check_quota_exceeded`. schema: *id027 X-RateLimit-Reset: description: When the window resets, in Unix seconds. Absent on `ip_rate_limited` and `check_quota_exceeded`. schema: *id028 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: check_quota_exceeded message: Each location may run at most 3 checks an hour. Retry after the number of seconds in `Retry-After`. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The check cannot start: the location has no Talki number, which an inactive one never has (`phone_number_missing`), no `forwarding_number` (`forwarding_number_missing`) or one that cannot be rung (`forwarding_number_invalid`), a check already running (`check_in_progress`), a test-mode credential (`livemode_required`), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key. `check_in_progress` clears by itself and is not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: check_in_progress message: A check is already running for this location. Poll GET /v1/forwarding_check; it ends within about a minute. request_id: req_7f24a2f8c6b64e699901563a458b5031 '502': description: The check call could not be placed (`check_call_failed`). Retry later. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: check_call_failed message: The check call could not be placed. Retry later. request_id: req_7f24a2f8c6b64e699901563a458b5031 '503': description: Too many checks are running across Talki (`checks_busy`). Retry after `Retry-After`. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: checks_busy message: Too many checks are running. Retry in a minute. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/forwarding_check'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ forwarding-check-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nforwarding_check =\ \ talki.account.start_forwarding_check(\n idempotency_key=\"forwarding-check-1\"\ ,\n)\nprint(forwarding_check)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst forwardingCheck = await talki.account.startForwardingCheck({\n \ \ idempotencyKey: \"forwarding-check-1\",\n});\nconsole.log(forwardingCheck);" /v1/agent_test: post: tags: - Agent test summary: Send a test message description: 'Send one message to the account''s assistant, as a caller would say it, and return its answer: what a call to the location would hear, from the same settings, documents, services, calendar and partner tools, written as text. Nothing is saved: a booking the assistant makes is not made, and no call, appointment or unresolved request is recorded. The first message starts a session; send its `session_id` with the next ones. Talki keeps the history for 30 minutes after the last turn, and a session holds at most 20 turns (then `agent_test_session_full`). A session belongs to the credential that started it. Your app''s own partner tools run, sent with `test_drive: true`, writes included; no other app''s do. The assistant here runs on a text model, not the one that answers calls, so a reply can be worded differently from what a caller would hear. Refused while the managing partner has suspended the account (`account_suspended`). An account may send 25 test messages a day, shared with the test in the Talki apps, and an OAuth app 300 a day across all the accounts it is installed on; past either, `429` `rate_limit_exceeded` with `Retry-After`. Requires `account:write` and `knowledge:read`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 15 test messages per minute.' operationId: sendAgentTest requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentTestMessage' example: message: Siete aperti sabato mattina? required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentTestReply' example: session_id: ats_5f0c2a9e7d4b4e1c8a3f6b2d9e7c1a04 reply: Sì, sabato siamo aperti dalle 9 alle 13. Vuole che le fissi un appuntamento? turn: 1 max_turns: 20 expires_at: '2026-11-09T10:30:00Z' daily_remaining: 24 tools_called: - check_availability headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: 'The account has sent its 25 test messages today, or the OAuth app 300 across all the accounts it is installed on: `Retry-After` is the seconds until midnight in the account''s `timezone`. Or the request rate was exceeded: 15 test messages a minute per account (API key) or installation (OAuth), on top of the write limit (`ip_rate_limited` for the calling address).' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: This account may send 25 test messages a day, shared with the test in the Talki apps. Retry after the number of seconds in `Retry-After`. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The session holds its 20 turns (`agent_test_session_full`): start a new one. Or another message of the session is still being answered (`request_conflict`): wait for its reply. Or the managing partner has suspended the account (`account_suspended`). Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key. `request_conflict` clears by itself and is not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: agent_test_session_full message: A test session holds at most 20 turns. Start a new one by sending a message without session_id. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No session with this `session_id` belongs to this credential, or it expired 30 minutes after its last turn; or `location_id` names no location of the account (`resource_not_found`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such agent test session. request_id: req_7f24a2f8c6b64e699901563a458b5031 '503': description: Testing the assistant through the API is switched off for now (`agent_test_unavailable`). Retry later. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: agent_test_unavailable message: Testing the assistant through the API is switched off for now. Retry later. request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/agent_test'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ agent-test-1\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"message\":\"Siete aperti sabato mattina?\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nagent_test_reply =\ \ talki.agent_test.send(\n body={\"message\": \"Siete aperti sabato mattina?\"\ },\n idempotency_key=\"agent-test-1\",\n)\nprint(agent_test_reply)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst agentTestReply = await talki.agentTest.send({\n body: { message:\ \ \"Siete aperti sabato mattina?\" },\n idempotencyKey: \"agent-test-1\"\ ,\n});\nconsole.log(agentTestReply);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: agent-test-1 /v1/agent_test/{session_id}: delete: tags: - Agent test summary: End a test session description: Drop a test session and its history now, rather than 30 minutes after its last turn. Only the credential that started it can end it. Refused with `409` `request_conflict` while a message of the session is being answered. Requires `account:write` and `knowledge:read`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: endAgentTest security: - ApiKeyAuth: [] parameters: - name: session_id in: path required: true schema: type: string description: The `session_id` a `POST /v1/agent_test` reply returned. title: Session Id description: The `session_id` a `POST /v1/agent_test` reply returned. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: agent-test-end-1 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No test session with this ID was started by this credential, or it has already ended or expired (30 minutes after its last turn). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such agent test session. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'A message of this session is still being answered (`request_conflict`): wait for its reply, then end it. Also returned when the idempotency key was reused for a different request (`idempotency_key_reuse`), or while a request with the same key is still being processed (`request_in_progress`): retry for its result.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: request_conflict message: A message of this session is still being answered. Wait for its reply, then end it. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/agent_test/ats_5f0c2a9e7d4b4e1c8a3f6b2d9e7c1a04'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ agent-test-end-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.agent_test.end(\n\ \ \"ats_5f0c2a9e7d4b4e1c8a3f6b2d9e7c1a04\",\n idempotency_key=\"agent-test-end-1\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.agentTest.end(\"ats_5f0c2a9e7d4b4e1c8a3f6b2d9e7c1a04\", {\n\ \ idempotencyKey: \"agent-test-end-1\",\n});" /v1/usage: get: tags: - Usage summary: Retrieve usage operationId: getUsage responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Usage' example: unlimited: false used_seconds: 4210 included_seconds: 18000 extra_seconds: 1800 allowance_seconds: 19800 remaining_seconds: 15590 period_start: '2026-10-01T00:00:00Z' resets_at: '2026-10-31T23:00:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] description: 'Return the talk time used in the current period, what is left, and when it resets, for the whole account: the meter is one for every location. For one location''s talk time, read the current month of `GET /v1/usage/history` with its `location_id`; that month can differ from this meter, as `UsageHistory` explains. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth).' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/usage' \\\n\ \ -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() usage = talki.usage.get() print(usage)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const usage = await talki.usage.get(); console.log(usage);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 /v1/usage/history: get: tags: - Usage summary: Retrieve usage history description: Return the talk time billed in each calendar month, up to 13 months, oldest first. A call counts, whole, in the month it was answered in. With `location_id`, only the calls of that location count. Requires `account:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: getUsageHistory security: - ApiKeyAuth: [] parameters: - name: from in: query required: false schema: anyOf: - type: string - type: 'null' description: 'First month, `YYYY-MM`. Default: 12 months before `to`.' title: From description: 'First month, `YYYY-MM`. Default: 12 months before `to`.' - name: to in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Last month, included, `YYYY-MM`. Default: the current month, which is still counting. Not after the current month. At most 13 months from `from`.' title: To description: 'Last month, included, `YYYY-MM`. Default: the current month, which is still counting. Not after the current month. At most 13 months from `from`.' - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations` (inactive ones included). Omit for every location. Each call belongs to one location, so the locations' months add up to the account's. title: Location Id description: Only the calls of this location (`Call.location_id`), an id from `GET /v1/locations` (inactive ones included). Omit for every location. Each call belongs to one location, so the locations' months add up to the account's. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UsageHistory' example: months: - month: 2026-09 start: '2026-08-31T22:00:00Z' end: '2026-09-30T22:00:00Z' used_seconds: 17940 calls: 118 - month: 2026-10 start: '2026-09-30T22:00:00Z' end: '2026-10-31T23:00:00Z' used_seconds: 4210 calls: 29 retained_since: '2025-10-08T00:00:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/usage/history?from=2026-05&to=2026-10&location_id=0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nusage_history = talki.usage.get_history(\n\ \ from_=\"2026-05\",\n to=\"2026-10\",\n location_id=\"0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40\"\ ,\n)\nprint(usage_history)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst usageHistory = await talki.usage.getHistory({\n from: \"2026-05\"\ ,\n to: \"2026-10\",\n location_id: \"0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40\"\ ,\n});\nconsole.log(usageHistory);" /v1/availability: get: tags: - Availability summary: Retrieve availability operationId: getAvailability security: - ApiKeyAuth: [] parameters: - name: service_id in: query required: true schema: type: string description: 'The service to check. Required. Availability is per service: two services that share a resource can return different windows.' title: Service Id description: 'The service to check. Required. Availability is per service: two services that share a resource can return different windows.' - name: from in: query required: true schema: type: string description: First local date to report, `YYYY-MM-DD`, in the account's timezone. Inclusive. format: date title: From description: First local date to report, `YYYY-MM-DD`, in the account's timezone. Inclusive. - name: to in: query required: true schema: type: string description: Last local date to report, `YYYY-MM-DD`. Inclusive, so `from` equal to `to` asks about one day. At most 62 days per request. format: date title: To description: Last local date to report, `YYYY-MM-DD`. Inclusive, so `from` equal to `to` asks about one day. At most 62 days per request. - name: quantity in: query required: false schema: type: integer minimum: 1 description: 'Party size, for a service that asks for one (`asks_quantity` on `GET /v1/services`). Pass the party size you intend to book: the windows depend on it. Ignored, and forced to 1, for a service that does not ask. Outside the service''s `min_quantity`/`max_quantity` it is refused with 400 `invalid_parameter`, as the booking would be.' default: 1 title: Quantity description: 'Party size, for a service that asks for one (`asks_quantity` on `GET /v1/services`). Pass the party size you intend to book: the windows depend on it. Ignored, and forced to 1, for a service that does not ask. Outside the service''s `min_quantity`/`max_quantity` it is refused with 400 `invalid_parameter`, as the booking would be.' - name: stay_length in: query required: false schema: anyOf: - type: integer maximum: 366 minimum: 1 - type: 'null' description: Length of the stay, in the service's `range_unit` (nights or days). **Required for a `day_range` service and rejected for any other.** Each date in the range then answers whether a stay of this length can begin on it. title: Stay Length description: Length of the stay, in the service's `range_unit` (nights or days). **Required for a `day_range` service and rejected for any other.** Each date in the range then answers whether a stay of this length can begin on it. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Availability' example: service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 timezone: Europe/Rome duration_minutes: 30 quantity: 1 days: - date: '2026-10-08' closed: false intervals: - start_at: '2026-10-08T07:00:00Z' end_at: '2026-10-08T11:00:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No service with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such service. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return advisory bookable windows for one service and local date range. Requires `availability:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/availability?service_id=45c470b7-592a-42cd-8ce8-5d7a0a497d26&from=2026-10-08&to=2026-10-10&quantity=1'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: "from datetime import date\n\nfrom talki import Talki\n\ntalki = Talki()\n\ \navailability = talki.availability.get(\n service_id=\"45c470b7-592a-42cd-8ce8-5d7a0a497d26\"\ ,\n from_=date(2026, 10, 8),\n to=date(2026, 10, 10),\n quantity=1,\n\ )\nprint(availability)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst availability = await talki.availability.get({\n service_id: \"\ 45c470b7-592a-42cd-8ce8-5d7a0a497d26\",\n from: \"2026-10-08\",\n to:\ \ \"2026-10-10\",\n quantity: 1,\n});\nconsole.log(availability);" /v1/appointments/{appointment_id}/restore: post: tags: - Appointments summary: Restore an appointment description: 'Undo a cancellation, keeping the ID. Refused with a conflict code when the time no longer fits, and with `service_deleted` when a service of the booking has been deleted and that service''s part of the booking ends in the future: book it again with a service that exists. Refused with `location_inactive` when the booking''s location is switched off. Requires `Idempotency-Key`. Requires `appointments:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' operationId: restoreAppointment security: - ApiKeyAuth: [] parameters: - name: appointment_id in: path required: true schema: type: string title: Appointment Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: restore-crm-1042 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Appointment' example: id: a3fe45ee-572f-4677-b1dd-f36c21bb47de location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: active client: *id029 service: *id030 start_at: '2026-10-08T09:00:00Z' end_at: '2026-10-08T09:30:00Z' quantity: 1 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 notes: First visit created_at: '2026-09-15T09:18:03Z' updated_at: '2026-10-07T10:12:45Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter or body field is invalid (`invalid_parameter`); the booking cannot be made at any time (`service_deleted`, `location_inactive`, or another `400` booking code); `Idempotency-Key` is missing (`idempotency_key_required`); or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: service_deleted message: A service of this booking has been deleted, so the booking cannot be restored or moved to a time still to come. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No appointment with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such appointment. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The appointment is not cancelled (`appointment_not_cancelled`), or the time no longer fits (`slot_unavailable` and the other booking conflict codes), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: slot_unavailable message: That time is no longer available. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/appointments/a3fe45ee-572f-4677-b1dd-f36c21bb47de/restore'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ restore-crm-1042\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nappointment = talki.appointments.restore(\n\ \ \"a3fe45ee-572f-4677-b1dd-f36c21bb47de\",\n idempotency_key=\"restore-crm-1042\"\ ,\n)\nprint(appointment)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst appointment = await talki.appointments.restore(\n \"a3fe45ee-572f-4677-b1dd-f36c21bb47de\"\ ,\n { idempotencyKey: \"restore-crm-1042\" },\n);\nconsole.log(appointment);" /v1/tags: get: tags: - Tags summary: List tags operationId: listTags responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TagList' example: data: - &id032 id: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Suppliers color: '#e0867a' contact_ids: &id031 - 8fbb25f2-4f3b-4496-8aea-f0fc66de512d created_at: '2026-10-01T08:00:00Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] description: Return every tag with the contacts that carry it. Requires `contacts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/tags' \\\n\ \ -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() tag_list = talki.tags.list() print(tag_list)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const tagList = await talki.tags.list(); console.log(tagList);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 post: tags: - Tags summary: Create a tag description: Create a tag. An account holds at most 50. Requires `Idempotency-Key`. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 20 creations per minute shared by the services, resources, tags and caller rules you create. operationId: createTag requestBody: content: application/json: schema: $ref: '#/components/schemas/TagCreate' example: name: Suppliers color: '#e0867a' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tag' example: id: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Suppliers color: '#e0867a' contact_ids: [] created_at: '2026-10-01T08:00:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The account already holds 50 tags (`tag_limit_reached`), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: tag_limit_reached message: An account holds at most 50 tags. Delete one first. request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/tags' \\\n\ \ -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ tag-create-suppliers\" \\\n -H \"Content-Type: application/json\" \\\n\ \ --data '{\"name\":\"Suppliers\",\"color\":\"#e0867a\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntag = talki.tags.create(\n\ \ body={\"name\": \"Suppliers\", \"color\": \"#e0867a\"},\n idempotency_key=\"\ tag-create-suppliers\",\n)\nprint(tag)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst tag = await talki.tags.create({\n body: { name: \"Suppliers\",\ \ color: \"#e0867a\" },\n idempotencyKey: \"tag-create-suppliers\",\n});\n\ console.log(tag);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: tag-create-suppliers /v1/tags/{tag_id}: patch: tags: - Tags summary: Update a tag description: Rename or recolour a tag. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateTag security: - ApiKeyAuth: [] parameters: - name: tag_id in: path required: true schema: type: string title: Tag Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: tag-rename-suppliers requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TagUpdate' example: name: Wholesale suppliers responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tag' example: id: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Wholesale suppliers color: '#e0867a' contact_ids: *id031 created_at: '2026-10-01T08:00:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No tag with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such tag. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/tags/4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ tag-rename-suppliers\" \\\n -H \"Content-Type: application/json\" \\\n\ \ --data '{\"name\":\"Wholesale suppliers\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntag = talki.tags.update(\n\ \ \"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\",\n body={\"name\": \"Wholesale\ \ suppliers\"},\n idempotency_key=\"tag-rename-suppliers\",\n)\nprint(tag)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst tag = await talki.tags.update(\"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\"\ , {\n body: { name: \"Wholesale suppliers\" },\n idempotencyKey: \"tag-rename-suppliers\"\ ,\n});\nconsole.log(tag);" delete: tags: - Tags summary: Delete a tag description: Delete a tag. The contacts it was on are not affected. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: deleteTag security: - ApiKeyAuth: [] parameters: - name: tag_id in: path required: true schema: type: string title: Tag Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: tag-delete-suppliers responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No tag with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such tag. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/tags/4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ tag-delete-suppliers\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.tags.delete(\n\ \ \"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\",\n idempotency_key=\"tag-delete-suppliers\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.tags.delete(\"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\", {\n\ \ idempotencyKey: \"tag-delete-suppliers\",\n});" /v1/tags/{tag_id}/contacts/{contact_id}: put: tags: - Tags summary: Tag a contact description: Put a tag on a contact. Idempotent. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: tagContact security: - ApiKeyAuth: [] parameters: - name: tag_id in: path required: true schema: type: string title: Tag Id - name: contact_id in: path required: true schema: type: string title: Contact Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: tag-contact-42 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tag' example: *id032 headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No tag or contact with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such tag or contact. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PUT 'https://api.talki.it/v1/tags/4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014/contacts/8fbb25f2-4f3b-4496-8aea-f0fc66de512d'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ tag-contact-42\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntag = talki.tags.tag_contact(\n\ \ \"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\",\n \"8fbb25f2-4f3b-4496-8aea-f0fc66de512d\"\ ,\n idempotency_key=\"tag-contact-42\",\n)\nprint(tag)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst tag = await talki.tags.tagContact(\n \"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\"\ ,\n \"8fbb25f2-4f3b-4496-8aea-f0fc66de512d\",\n { idempotencyKey: \"tag-contact-42\"\ \ },\n);\nconsole.log(tag);" delete: tags: - Tags summary: Untag a contact description: Take a tag off a contact and return the tag. Idempotent. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: untagContact security: - ApiKeyAuth: [] parameters: - name: tag_id in: path required: true schema: type: string title: Tag Id - name: contact_id in: path required: true schema: type: string title: Contact Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: untag-contact-42 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Tag' example: id: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Suppliers color: '#e0867a' contact_ids: [] created_at: '2026-10-01T08:00:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No tag or contact with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such tag or contact. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/tags/4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014/contacts/8fbb25f2-4f3b-4496-8aea-f0fc66de512d'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ untag-contact-42\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntag = talki.tags.untag_contact(\n\ \ \"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\",\n \"8fbb25f2-4f3b-4496-8aea-f0fc66de512d\"\ ,\n idempotency_key=\"untag-contact-42\",\n)\nprint(tag)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst tag = await talki.tags.untagContact(\n \"4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014\"\ ,\n \"8fbb25f2-4f3b-4496-8aea-f0fc66de512d\",\n { idempotencyKey: \"untag-contact-42\"\ \ },\n);\nconsole.log(tag);" /v1/pending_contacts: get: tags: - Pending contacts summary: List pending contacts operationId: listPendingContacts responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PendingContactList' example: data: - id: d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68 phone_number: '+393334445555' first_name: Giulia last_name: null call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 created_at: '2026-10-06T15:02:44Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] description: Return the names the assistant heard that wait for the owner, newest first. Requires `contacts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/pending_contacts'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() pending_contact_list = talki.pending_contacts.list() print(pending_contact_list)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const pendingContactList = await talki.pendingContacts.list(); console.log(pendingContactList);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 /v1/pending_contacts/{pending_id}/approve: post: tags: - Pending contacts summary: Approve a pending contact description: Make a pending contact a contact, with any corrections, and return the contact. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: approvePendingContact security: - ApiKeyAuth: [] parameters: - name: pending_id in: path required: true schema: type: string title: Pending Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: pending-approve-1 requestBody: content: application/json: schema: $ref: '#/components/schemas/PendingContactApproval' example: last_name: Verdi responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Contact' example: id: 2c6e8b14-9f3a-4d71-b05e-7a1c3d9e4f82 phone_number: '+393334445555' first_name: Giulia last_name: Verdi display_name: Giulia Verdi notes: null last_call_at: '2026-10-06T14:58:12Z' call_count: 1 created_at: '2026-10-07T08:20:15Z' updated_at: '2026-10-07T08:20:15Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No pending contact with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such pending contact. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/pending_contacts/d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68/approve'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ pending-approve-1\" \\\n -H \"Content-Type: application/json\" \\\n \ \ --data '{\"last_name\":\"Verdi\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ncontact = talki.pending_contacts.approve(\n\ \ \"d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68\",\n body={\"last_name\"\ : \"Verdi\"},\n idempotency_key=\"pending-approve-1\",\n)\nprint(contact)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst contact = await talki.pendingContacts.approve(\n \"d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68\"\ ,\n { body: { last_name: \"Verdi\" }, idempotencyKey: \"pending-approve-1\"\ \ },\n);\nconsole.log(contact);" /v1/pending_contacts/{pending_id}: delete: tags: - Pending contacts summary: Discard a pending contact description: Forget a pending contact. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: discardPendingContact security: - ApiKeyAuth: [] parameters: - name: pending_id in: path required: true schema: type: string title: Pending Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: pending-discard-1 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No pending contact with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such pending contact. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/pending_contacts/d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ pending-discard-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.pending_contacts.discard(\n\ \ \"d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68\",\n idempotency_key=\"pending-discard-1\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.pendingContacts.discard(\"d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68\"\ , {\n idempotencyKey: \"pending-discard-1\",\n});" /v1/caller_rules: get: tags: - Caller rules summary: List caller rules operationId: listCallerRules security: - ApiKeyAuth: [] parameters: - name: kind in: query required: false schema: anyOf: - $ref: '#/components/schemas/CallerRuleKind' - type: 'null' description: Only `vip` or only `blocked` numbers. Omit for both. title: Kind description: Only `vip` or only `blocked` numbers. Omit for both. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of rules to return. default: 50 title: Limit description: Maximum number of rules to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. title: Cursor description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallerRuleList' example: data: - &id033 id: 93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30 phone_number: '+393401234567' location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 kind: blocked label: Telemarketing created_at: '2026-10-02T09:10:00Z' updated_at: '2026-10-02T09:10:00Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: Return the VIP and blocked numbers, newest first. Requires `contacts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/caller_rules?kind=blocked&limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki from talki.models import CallerRuleKind talki = Talki() page = talki.caller_rules.list(kind=CallerRuleKind.BLOCKED, limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.callerRules.list({ kind: "blocked", limit: 10 }); console.log(page.data);' post: tags: - Caller rules summary: Add a caller rule description: 'Add a number to the VIP or blocked list: `201` with the new rule. A number that already has a rule answers `200` with it, moved or relabelled as the request asks, or unchanged. Requires `Idempotency-Key`. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 20 creations per minute shared by the services, resources, tags and caller rules you create.' operationId: createCallerRule security: - ApiKeyAuth: [] parameters: - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The location to add the number at, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. title: Location Id description: The location to add the number at, an id from `GET /v1/locations` (inactive ones included). Omit it for the main location. - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: true description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: block-spam-1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallerRuleCreate' example: phone_number: '+393401234567' kind: blocked label: Telemarketing responses: '201': description: A rule was created for the number. content: application/json: schema: $ref: '#/components/schemas/CallerRule' example: *id033 headers: X-Request-Id: &id034 description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: &id035 description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: &id036 description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '200': description: The number already had a rule. It is returned moved to this list or relabelled if the request asks for that, or unchanged. headers: X-Request-Id: *id034 Talki-Version: *id035 Idempotency-Replayed: *id036 content: application/json: schema: $ref: '#/components/schemas/CallerRule' example: id: 93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30 phone_number: '+393401234567' location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 kind: blocked label: Telemarketing created_at: '2026-10-02T09:10:00Z' updated_at: '2026-10-07T16:30:00Z' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The location''s list is full (`caller_rule_limit_reached`: 50 VIP, 200 blocked), another request added the same number at the same moment (`request_conflict`: retry with the same idempotency key, and the retry answers `200` with the rule), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key. `request_conflict` clears by itself and is not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: caller_rule_limit_reached message: A location holds at most 200 blocked numbers. Remove one first. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/caller_rules'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ block-spam-1\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"phone_number\":\"+393401234567\",\"kind\":\"blocked\",\"label\":\"\ Telemarketing\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ncaller_rule = talki.caller_rules.create(\n\ \ body={\n \"phone_number\": \"+393401234567\",\n \"kind\"\ : \"blocked\",\n \"label\": \"Telemarketing\",\n },\n idempotency_key=\"\ block-spam-1\",\n)\nprint(caller_rule)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst callerRule = await talki.callerRules.create({\n body: { phone_number:\ \ \"+393401234567\", kind: \"blocked\", label: \"Telemarketing\" },\n idempotencyKey:\ \ \"block-spam-1\",\n});\nconsole.log(callerRule);" /v1/caller_rules/blocked_attempts: get: tags: - Caller rules summary: List blocked calls description: Return the calls refused because their number is blocked, newest first. Requires `contacts:read`. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listBlockedCallAttempts security: - ApiKeyAuth: [] parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of attempts to return. default: 50 title: Limit description: Maximum number of attempts to return. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. title: Cursor description: Opaque cursor from a previous response's `next_cursor`. Omit for the first page. - name: location_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`.' title: Location Id description: 'Only the records of this location, an id from `GET /v1/locations` (inactive ones included). Omit for every location: each record carries its `location_id`.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BlockedCallAttemptList' example: data: - id: f1a8d3c6-4e27-4b90-8c5d-2e7b9a0f6d13 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 phone_number: '+393401234567' label: Telemarketing attempted_at: '2026-10-05T11:47:03Z' next_cursor: null has_more: false headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: '`location_id` names no location of the authenticated account.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such location. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/caller_rules/blocked_attempts?limit=10'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() page = talki.caller_rules.list_blocked_call_attempts(limit=10) print(page.data)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const page = await talki.callerRules.listBlockedCallAttempts({ limit: 10 }); console.log(page.data);' /v1/caller_rules/{rule_id}: patch: tags: - Caller rules summary: Update a caller rule description: Move a rule to the other list or relabel it. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: updateCallerRule security: - ApiKeyAuth: [] parameters: - name: rule_id in: path required: true schema: type: string title: Rule Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: rule-move-1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallerRuleUpdate' example: kind: vip label: Supplier responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallerRule' example: id: 93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30 phone_number: '+393401234567' location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 kind: vip label: Supplier created_at: '2026-10-02T09:10:00Z' updated_at: '2026-10-07T16:30:00Z' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No caller rule with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such caller rule. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The destination list is full (`caller_rule_limit_reached`), or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: caller_rule_limit_reached message: A location holds at most 50 vip numbers. Remove one first. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X PATCH 'https://api.talki.it/v1/caller_rules/93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ rule-move-1\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"kind\":\"vip\",\"label\":\"Supplier\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ncaller_rule = talki.caller_rules.update(\n\ \ \"93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30\",\n body={\"kind\": \"vip\"\ , \"label\": \"Supplier\"},\n idempotency_key=\"rule-move-1\",\n)\nprint(caller_rule)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst callerRule = await talki.callerRules.update(\n \"93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30\"\ ,\n { body: { kind: \"vip\", label: \"Supplier\" }, idempotencyKey: \"\ rule-move-1\" },\n);\nconsole.log(callerRule);" delete: tags: - Caller rules summary: Delete a caller rule description: Remove a number from its list. Requires `contacts:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth). operationId: deleteCallerRule security: - ApiKeyAuth: [] parameters: - name: rule_id in: path required: true schema: type: string title: Rule Id - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: rule-delete-1 responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No caller rule with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such caller rule. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/caller_rules/93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ rule-delete-1\"" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ntalki.caller_rules.delete(\n\ \ \"93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30\",\n idempotency_key=\"rule-delete-1\"\ ,\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.callerRules.delete(\"93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30\"\ , {\n idempotencyKey: \"rule-delete-1\",\n});" /v1/documents/discover: post: tags: - Documents summary: Discover a site's pages operationId: discoverDocumentPages requestBody: content: application/json: schema: $ref: '#/components/schemas/DocumentDiscover' example: url: https://www.example.com required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentDiscovery' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 '502': description: The site could not be read (`api_error`). Check the address, or retry later. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: api_error message: The site could not be read. Check the address, or retry later. request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] description: Look for the pages of the site at `url`, from its sitemap or its links, to choose the `pages` of an import. Imports nothing. `max_pages` is how many one import may read on the account's plan. An address that is not public http or https, or any field besides `url`, is refused (`invalid_parameter`). Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 60 document writes per minute, shared by creating, replacing and updating documents and discovering a site's pages. x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/documents/discover'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ discover-bellini\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"url\":\"https://www.example.com\"}'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\ndocument_discovery\ \ = talki.documents.discover_pages(\n body={\"url\": \"https://www.example.com\"\ },\n idempotency_key=\"discover-bellini\",\n)\nprint(document_discovery)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst documentDiscovery = await talki.documents.discoverPages({\n body:\ \ { url: \"https://www.example.com\" },\n idempotencyKey: \"discover-bellini\"\ ,\n});\nconsole.log(documentDiscovery);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: discover-bellini /v1/documents/{document_id}/pages/{page_id}: delete: tags: - Documents summary: Delete a website's page operationId: deleteDocumentPage security: - ApiKeyAuth: [] parameters: - name: document_id in: path required: true schema: type: string title: Document Id - name: page_id in: path required: true schema: type: string title: Page Id - name: also in: query required: false schema: anyOf: - type: string enum: - copies - type: 'null' description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' title: Also description: '`copies` applies the change to every copy of the document at other locations too. Omit it to change only this document.' - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: site-drop-careers responses: '204': description: Successful Response headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: The account or credential may not perform this request. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: insufficient_scope message: This credential does not have the required scope. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: The document is not a website, the only kind with pages (`invalid_parameter`), or a parameter is invalid; or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: 'This document is a text note: only a website has pages.' request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: No document or page with this ID exists in the authenticated account. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: No such document or page. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: 'The site is being imported at the document or, with `also=copies`, at a copy (`document_not_ready`): retry once it is `ready` or `failed`, or without `also=copies` when a copy holds it up. Or dropping the page would leave no text to search while other pages are still listed as read (`conflict`): import the site again with the `pages` to keep, or delete the document; a retry meets the same answer. Or another request changed the document''s copies at the same time (`request_conflict`): retry. Or the idempotency key was reused for a different request. Except `idempotency_key_reuse`, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key. `request_conflict` and `document_not_ready` clear by themselves and are not kept: retry with the same key.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: document_not_ready message: The site is still being imported. Retry once the document's `status` is no longer `processing`. request_id: req_7f24a2f8c6b64e699901563a458b5031 '503': description: The site's text cannot be read right now to drop the page (`api_error`). Retry later. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: api_error message: The knowledge index is temporarily unavailable. Retry later. request_id: req_7f24a2f8c6b64e699901563a458b5031 description: 'Drop one page of an imported website and what it said; the assistant stops using it once the document is `ready` again. Dropping its last page that was read deletes the document (`document.deleted`). With `also=copies`, its copies at other locations get the result too. Only a website has pages; any other document is refused (`invalid_parameter`). Refused while the site is being imported (`document_not_ready`), and (`conflict`) when dropping it would leave no text to search while other pages are still listed as read: import the site again with the `pages` to keep, or delete the document. Requires `knowledge:write`. Limited to 120 requests per minute per account (API key) or per installation (OAuth).' x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X DELETE 'https://api.talki.it/v1/documents/5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36/pages/8e3a1c57-b2d4-4f9e-a6c0-5d7f1b9e2a43?also=copies'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ site-drop-careers\"" - lang: python label: Python source: "from talki import Talki\nfrom talki.models import DocumentAlso\n\n\ talki = Talki()\n\ntalki.documents.delete_page(\n \"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ ,\n \"8e3a1c57-b2d4-4f9e-a6c0-5d7f1b9e2a43\",\n also=DocumentAlso.COPIES,\n\ \ idempotency_key=\"site-drop-careers\",\n)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nawait talki.documents.deletePage(\n \"5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36\"\ ,\n \"8e3a1c57-b2d4-4f9e-a6c0-5d7f1b9e2a43\",\n { also: \"copies\", idempotencyKey:\ \ \"site-drop-careers\" },\n);" /v1/sandbox/scenarios: get: tags: - Sandbox summary: List sandbox scenarios description: Return the named calls this sandbox can be told it had, with the exact events each one emits. Requires a developer sandbox; answers 404 on a real account. Limited to 600 requests per minute per account (API key) or per installation (OAuth). operationId: listSandboxScenarios responses: '200': description: Successful Response content: application/json: schema: items: $ref: '#/components/schemas/ScenarioSummary' type: array title: Response List Scenarios V1 Sandbox Scenarios Get headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: An OAuth access token was used; sandbox controls require the sandbox API key. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: sandbox_api_key_required message: Sandbox controls require a sandbox API key. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: The credential does not belong to a developer sandbox. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: This endpoint exists only on a developer sandbox. The credential you used belongs to a real Talki account. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: '`Talki-Version`, or the credential''s pin, names a version this API does not serve.' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: unsupported_version message: '''2025-01-01'' is not a supported API version. Supported: 2026-10-01.' request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X GET 'https://api.talki.it/v1/sandbox/scenarios'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() result = talki.sandbox.list_scenarios() print(result)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const result = await talki.sandbox.listScenarios(); console.log(result);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 /v1/sandbox/calls: post: tags: - Sandbox summary: Create a sandbox call description: 'Tell the sandbox it had a call. The whole post-call flow runs for real, including signed webhook deliveries carrying `livemode: false`. Requires a developer sandbox; answers 404 on a real account. Limited to 30 requests per minute per account (API key) or per installation (OAuth).' operationId: createSandboxCall requestBody: content: application/json: schema: $ref: '#/components/schemas/FakeCallRequest' example: scenario: booking_created caller_phone: '+393480000001' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FakeCallResponse' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: An OAuth access token was used; sandbox controls require the sandbox API key. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: sandbox_api_key_required message: Sandbox controls require a sandbox API key. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: The credential does not belong to a developer sandbox. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: This endpoint exists only on a developer sandbox. The credential you used belongs to a real Talki account. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/sandbox/calls'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ sandbox-call-1\" \\\n -H \"Content-Type: application/json\" \\\n --data\ \ '{\"scenario\":\"booking_created\",\"caller_phone\":\"+393480000001\"\ }'" - lang: python label: Python source: "from talki import Talki\n\ntalki = Talki()\n\nfake_call_response\ \ = talki.sandbox.create_call(\n body={\"scenario\": \"booking_created\"\ , \"caller_phone\": \"+393480000001\"},\n idempotency_key=\"sandbox-call-1\"\ ,\n)\nprint(fake_call_response)" - lang: ts label: TypeScript source: "import { Talki } from \"@hubtec/talki\";\n\nconst talki = new Talki();\n\ \nconst fakeCallResponse = await talki.sandbox.createCall({\n body: { scenario:\ \ \"booking_created\", caller_phone: \"+393480000001\" },\n idempotencyKey:\ \ \"sandbox-call-1\",\n});\nconsole.log(fakeCallResponse);" parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: sandbox-call-1 /v1/sandbox/reset: post: tags: - Sandbox summary: Reset the sandbox description: 'Delete this sandbox''s history and rebuild it from a fixed seed. API keys, installations, services and locations survive. Webhook endpoints do not: the account''s endpoints and their deliveries are deleted and replaced by the seed''s one paused endpoint, and the account events still queued for an app are dropped. Register your endpoints again after a reset. Requires a developer sandbox; answers 404 on a real account. Limited to 6 requests per minute per account (API key) or per installation (OAuth).' operationId: resetSandbox responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ResetResponse' headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string Talki-Version: description: The dated contract version this response was served at. schema: type: string example: '2026-10-01' Idempotency-Replayed: description: '`true` when this response was replayed from a prior request with the same key.' schema: type: string enum: - 'true' '401': description: The credential is missing, malformed, expired, revoked, or unknown. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_credentials message: The supplied API credential is invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '402': description: The account does not have an active subscription. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: subscription_inactive message: This account does not have an active subscription. request_id: req_7f24a2f8c6b64e699901563a458b5031 '403': description: An OAuth access token was used; sandbox controls require the sandbox API key. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: permission_error code: sandbox_api_key_required message: Sandbox controls require a sandbox API key. request_id: req_7f24a2f8c6b64e699901563a458b5031 '404': description: The credential does not belong to a developer sandbox. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: resource_not_found message: This endpoint exists only on a developer sandbox. The credential you used belongs to a real Talki account. request_id: req_7f24a2f8c6b64e699901563a458b5031 '429': description: The account or installation exceeded its request rate (`rate_limit_exceeded`), or the calling address did (`ip_rate_limited`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 Retry-After: *id005 X-RateLimit-Limit: *id006 X-RateLimit-Remaining: *id007 X-RateLimit-Reset: *id008 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Retry after the interval in Retry-After. request_id: req_7f24a2f8c6b64e699901563a458b5031 '500': description: An unexpected error occurred. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: internal_error message: An unexpected error occurred. Quote the request_id when reporting it. request_id: req_7f24a2f8c6b64e699901563a458b5031 '400': description: A parameter, cursor, body field, or required idempotency key is invalid, or `Talki-Version` names an unsupported version (`unsupported_version`). headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_parameter message: One or more request values are invalid. request_id: req_7f24a2f8c6b64e699901563a458b5031 '409': description: The write conflicts with current state or a previous idempotency key use. headers: X-Request-Id: description: Identifier to include when contacting Talki support. schema: type: string example: req_7f24a2f8c6b64e699901563a458b5031 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: conflict code: idempotency_key_reuse message: This Idempotency-Key was already used for a different request. request_id: req_7f24a2f8c6b64e699901563a458b5031 security: - ApiKeyAuth: [] x-codeSamples: - lang: sh label: cURL source: "curl --fail-with-body -X POST 'https://api.talki.it/v1/sandbox/reset'\ \ \\\n -H \"Authorization: Bearer $TALKI_API_KEY\" \\\n -H \"Idempotency-Key:\ \ sandbox-reset-1\"" - lang: python label: Python source: 'from talki import Talki talki = Talki() reset_response = talki.sandbox.reset(idempotency_key="sandbox-reset-1") print(reset_response)' - lang: ts label: TypeScript source: 'import { Talki } from "@hubtec/talki"; const talki = new Talki(); const resetResponse = await talki.sandbox.reset({ idempotencyKey: "sandbox-reset-1" }); console.log(resetResponse);' parameters: - name: Talki-Version in: header required: false description: Serve this one request at the given dated contract version instead of the credential's pin. An unsupported value is refused with `400 unsupported_version`, never downgraded. schema: *id001 - name: Idempotency-Key in: header required: false description: 'Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked `Idempotency-Replayed: true`, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a `400` asking for a different request (`invalid_parameter`, `invalid_cursor`, `export_too_large`, `unknown_scenario`, `no_services_requested`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`), a `415`, a `409` `request_conflict`, `document_not_ready` or `check_in_progress`, a `412`, a `429` and a `5xx`.' schema: type: string maxLength: 255 example: sandbox-reset-1 components: schemas: Account: properties: id: type: string title: Id description: Opaque Talki account identifier. location_id: type: string title: Location Id description: 'The location these settings are of, an id from `GET /v1/locations`: the one the request named with `location_id`, or the main location when it named none.' business_name: anyOf: - type: string - type: 'null' title: Business Name description: The trading name the assistant uses for the business. Null if not yet configured. timezone: type: string title: Timezone description: IANA timezone all naive local times for this account resolve against. livemode: type: boolean title: Livemode description: 'False when this credential does not act on real data: a test-mode key (`talki_test_…`), or an app installed on a developer sandbox or on a test account. Webhook envelopes carry the same flag.' test: type: boolean title: Test description: 'True for a test account your app created with `"test": true` on `POST /oauth/managed-accounts`. It has no Talki number, nobody is billed for it or emailed, and it is erased seven days after it was created. Its `livemode` is false.' business_information: anyOf: - type: string - type: 'null' title: Business Information description: 'Facts about the business that the assistant can tell callers, as the owner wrote them in Talki under «Informazioni aggiuntive», such as "parking is free" or "we do not deliver". Null when empty. This is not the assistant''s full set of instructions: it sits inside Talki''s own rules, which cannot be read or changed.' instructions: anyOf: - type: string - type: 'null' title: Instructions description: Short orders about how the assistant should behave on a call, as the owner wrote them in Talki under «Istruzioni aggiuntive», such as "always use the formal lei" or "never quote prices on the phone". Null when empty. Like `business_information`, this sits inside Talki's own rules, which cannot be read or changed. voice: type: string title: Voice description: The voice the assistant speaks with on calls. One of the ids listed by `GET /v1/voices`. answers_as: allOf: - $ref: '#/components/schemas/AnswersAs' description: 'Which name the assistant answers calls in and speaks for: `business` uses `business_name`, `owner` uses the account holder''s own name. If the chosen name is empty, the other one is used.' greeting: anyOf: - type: string - type: 'null' title: Greeting description: What the assistant says right after its opening sentence, such as "Come posso aiutarla?". `{company_name}` and `{owner_name}` are replaced with the business name and the owner's name. Null when the assistant adds nothing after the opening. call_opening: anyOf: - type: string - type: 'null' title: Call Opening description: The start of the first sentence a caller hears, such as "Buongiorno, sono Isa". Talki always completes it with a fixed statement that the caller is speaking to a virtual assistant, which cannot be changed. Null means the default opening, "Buongiorno, sta parlando con Talki". A custom opening is spoken only while the account's plan includes it; otherwise the default is used and this value is kept. multilingual_enabled: type: boolean title: Multilingual Enabled description: True when the assistant may switch to English, French, German or Spanish to follow the caller. False keeps every call in Italian. The opening is always in Italian. languages: $ref: '#/components/schemas/AccountLanguages' description: The languages calls may be held in, derived from `multilingual_enabled`. Read only. service_area: anyOf: - type: string - type: 'null' title: Service Area description: Where the business works or delivers, as free text the assistant can tell callers, such as "Bergamo e provincia". Null when not set. transfer_numbers: items: $ref: '#/components/schemas/TransferNumber' type: array title: Transfer Numbers description: People or lines the assistant may hand a call over to. Empty when the assistant never transfers calls. bookings_enabled: type: boolean title: Bookings Enabled description: True when the assistant books, moves and cancels appointments on calls. False makes it answer questions and take messages only. Does not affect the appointment endpoints of this API. unresolved_requests_enabled: type: boolean title: Unresolved Requests Enabled description: True when the assistant offers to record a question it cannot answer, so the business can follow up. Recorded questions are listed by `GET /v1/unresolved_requests`. remember_callers: type: boolean title: Remember Callers description: True when the assistant recognises returning callers from the contact book and keeps notes about them for their next call. False treats every call as a first call and keeps nothing about the caller after it ends. notify_on_every_call: type: boolean title: Notify On Every Call description: 'True when the owner gets a push notification on the Talki mobile app after each call, with its summary. Push only, and only on phones where the owner is signed in to the app with notifications allowed; bookings, conflicts and unresolved questions push whatever this says. Talki sends no email or SMS per call: build those on the `call.ended` and `appointment.created` events.' notify_on_incoming_call: type: boolean title: Notify On Incoming Call description: True when the owner gets a push notification on the Talki mobile app while a call is ringing, naming the caller, for every caller. Callers marked VIP push whatever this says. Push only, as for `notify_on_every_call`. store_transcripts: type: boolean title: Store Transcripts description: True when the words of each call to this location are kept, readable through `GET /v1/calls/{id}/transcript`. Setting it to false deletes the transcripts already stored for this location's calls; call records and summaries are kept. phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: The Talki number that answers the location's calls, E.164. The business forwards the location's own line to it. Null until a number is assigned, and again once it is released; a location other than the main one has none while it is inactive. Read only; assigning or releasing it sends `account.updated` for the main location and `location.updated` for any other. forwarding_number: anyOf: - type: string - type: 'null' title: Forwarding Number description: The location's own line, which forwards its calls to `phone_number`, E.164. `POST /v1/forwarding_check` rings it to prove forwarding is on. Null when not set. line: $ref: '#/components/schemas/AccountLine' description: The location's Talki number, its line that forwards to it, and whether that forwarding has been proven. Read only. The same as `Location.line`. call_auto_archive_days: anyOf: - type: integer enum: - 7 - 30 - 90 - 180 - type: 'null' title: Call Auto Archive Days description: 'How many days after it started a call that has been read is archived on its own: `7`, `30`, `90` or `180`, as in the Talki apps. Null when calls are never archived on their own. An unread call is never archived this way. Archiving runs once a night, sends `call.updated` for each call, and can be undone like an archive by hand. The account''s own setting: the same at every location.' multi_sede: type: boolean title: Multi Sede description: 'True when the account works from several locations, or may add them: show locations (`GET /v1/locations`) to the owner only when true. False for an account that has only ever had its main location and cannot add another; it still has that one location, every record still carries its `location_id`, and nothing changes shape when this turns true. Read only.' onboarding_completed: type: boolean title: Onboarding Completed description: True once the account has finished setting up its assistant. While false, the Talki app opens its setup wizard. Set it with `POST /v1/account/complete_onboarding`; it never goes back to false. type: object required: - id - location_id - business_name - timezone - livemode - test - business_information - instructions - voice - answers_as - greeting - call_opening - multilingual_enabled - languages - service_area - transfer_numbers - bookings_enabled - unresolved_requests_enabled - remember_callers - notify_on_every_call - notify_on_incoming_call - store_transcripts - phone_number - forwarding_number - line - call_auto_archive_days - multi_sede - onboarding_completed title: Account description: 'The account a credential belongs to, and everything its owner sets up for the assistant: the business name and texts, the voice, the opening and greeting, the switches, the transfer numbers, and the line that forwards to Talki. `GET /v1/account` needs only `account:read`, which makes it the call to validate a new credential. The settings are those of one location: the main one, or the one `?location_id=` names, the switches included. Only the account''s own fields (`id`, `timezone`, `livemode`, `test`, `multi_sede`, `onboarding_completed` and `call_auto_archive_days`) read the same at every location. The response''s `ETag` covers every writable field at that location; send it back as `If-Match` on `PATCH /v1/account` with the same `location_id`. `account.updated` reports a change to the main location''s settings or to `call_auto_archive_days`, `location.settings_updated` one to another location''s settings, its switches included.' AccountLanguages: properties: primary: type: string title: Primary description: The language every call opens in, before the caller has said anything. Always `it` today. supported: items: type: string type: array title: Supported description: 'Every language the assistant may speak, `primary` first: `it` alone while `multilingual_enabled` is false, otherwise `it`, `en`, `fr`, `de` and `es`. More may be added. Read only: change it through `multilingual_enabled`.' type: object required: - primary - supported title: AccountLanguages description: 'The languages the assistant speaks on calls, ISO 639-1. Read only: change them through `multilingual_enabled`.' AccountLine: properties: phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: The Talki number calls are forwarded to, E.164; the same as `Account.phone_number`. forwarding_number: anyOf: - type: string - type: 'null' title: Forwarding Number description: The business's own line, E.164; the same as `Account.forwarding_number`. status: allOf: - $ref: '#/components/schemas/LineStatus' description: '`no_number` while the account has no Talki number. `unverified` until a forwarding check of the current `forwarding_number` has succeeded, including while no `forwarding_number` is set. `verified` once one has. It proves forwarding was on at `verified_at`, not that it still is: the business can switch it off at its carrier without Talki knowing. Changing `forwarding_number` returns it to `unverified`. A check that finds no forwarding does not change it; read that outcome from `GET /v1/forwarding_check`.' verified_at: anyOf: - type: string format: date-time - type: 'null' title: Verified At description: When a forwarding check of the current `forwarding_number` last succeeded, RFC 3339 UTC. Null unless `status` is `verified`. A successful check does not send `account.updated`. type: object required: - phone_number - forwarding_number - status - verified_at title: AccountLine description: 'How calls reach Talki: the location''s own line forwards to its Talki number. Read only. A check still ringing, or one that found no forwarding, is read from `GET /v1/forwarding_check`.' AccountUpdate: properties: business_name: anyOf: - type: string maxLength: 2000 - type: 'null' title: Business Name description: Replaces the business name. Send `null` or an empty string to clear it. business_information: anyOf: - type: string maxLength: 2000 - type: 'null' title: Business Information description: Replaces the business information. Send `null` or an empty string to clear it. instructions: anyOf: - type: string maxLength: 600 - type: 'null' title: Instructions description: 'Replaces the instructions. Send `null` or an empty string to clear them. Keep them to a few short orders: longer text makes each one less likely to be followed.' voice: title: Voice description: A voice id from `GET /v1/voices`. Cannot be null. type: string answers_as: title: Answers As description: '`business` or `owner`. Cannot be null.' $ref: '#/components/schemas/AnswersAs' greeting: anyOf: - type: string maxLength: 2000 - type: 'null' title: Greeting description: Replaces the greeting. May contain `{company_name}` and `{owner_name}`. Leading and trailing whitespace is removed. Send `null` or an empty string to clear it. call_opening: anyOf: - type: string - type: 'null' title: Call Opening description: Replaces the opening, at most 160 characters once runs of whitespace are collapsed to one space. May contain `{company_name}` and `{owner_name}`. Setting one needs a plan that includes a custom opening, or the request is refused with `plan_feature_unavailable`. Send `null` or an empty string to go back to the default, which every plan may do. multilingual_enabled: title: Multilingual Enabled description: Cannot be null. type: boolean service_area: anyOf: - type: string maxLength: 2000 - type: 'null' title: Service Area description: Replaces the service area. Send `null` or an empty string to clear it. transfer_numbers: title: Transfer Numbers description: 'The whole list, replacing every existing entry. Send an empty list to remove them all; `null` is refused. A non-empty list needs the main location''s `forwarding_number`, already stored or sent in the same request, and may not contain it, nor the location''s own `forwarding_number`: a call transferred there would come straight back to the assistant.' items: $ref: '#/components/schemas/TransferNumberInput' type: array maxItems: 20 bookings_enabled: title: Bookings Enabled description: Cannot be null. type: boolean unresolved_requests_enabled: title: Unresolved Requests Enabled description: Cannot be null. type: boolean remember_callers: title: Remember Callers description: Cannot be null. type: boolean notify_on_every_call: title: Notify On Every Call description: Cannot be null. type: boolean notify_on_incoming_call: title: Notify On Incoming Call description: Cannot be null. type: boolean store_transcripts: title: Store Transcripts description: Cannot be null. `false` deletes the stored transcripts of this location's calls in the same request, and they cannot be recovered, so a test-mode credential sending it is refused with `livemode_required`. type: boolean call_auto_archive_days: anyOf: - type: integer enum: - 7 - 30 - 90 - 180 - type: 'null' title: Call Auto Archive Days description: '`7`, `30`, `90` or `180`, or `null` to stop archiving calls on their own. The account''s own setting: refused with `location_id` naming a location other than the main one.' forwarding_number: anyOf: - type: string - type: 'null' title: Forwarding Number description: 'Replaces the location''s forwarding number: a mobile or landline that can be rung, E.164 or national (read as Italian). Send `null` or an empty string to clear it. Refused if it equals a transfer target of any location, or the line of another location, unless the same request replaces this location''s `transfer_numbers`. The main location''s cannot be cleared while any location has `transfer_numbers`. A change discards the result of the last forwarding check, and `last_verified_at` reads null until a check of the new number succeeds.' type: object title: AccountUpdate description: 'The settings you can change. Every field is optional and an omitted one is left unchanged, but send at least one. A `null` or empty text clears it; a voice, a switch or the transfer list cannot be null. With `?location_id=`, the settings change at that location only. `call_auto_archive_days` is the account''s: it is refused with a `location_id` other than the main location''s.' AgentTestMessage: properties: message: type: string maxLength: 1000 minLength: 1 title: Message description: What the caller says, at most 1,000 characters. session_id: anyOf: - type: string - type: 'null' title: Session Id description: The session to continue, from an earlier reply. Omit it to start a new one. location_id: anyOf: - type: string - type: 'null' title: Location Id description: 'The location whose assistant answers, an id from `GET /v1/locations`. Omit it for the main location. A session stays at the location it started at: with `session_id`, send the same one or none.' type: object required: - message title: AgentTestMessage description: 'One message to the assistant, as a caller would say it. Omit `session_id` to start a session, and send the one from the reply to continue it: Talki keeps the history, and there is no way to send one. A session stays at the location it started at.' AgentTestReply: properties: session_id: type: string title: Session Id description: The session this turn belongs to; send it with the next message. reply: type: string title: Reply description: What the assistant answered. turn: type: integer title: Turn description: This turn's number in the session, from 1. max_turns: type: integer title: Max Turns description: The most turns a session holds; start a new one after the last. expires_at: type: string title: Expires At description: When the session is dropped if no message continues it, 30 minutes after this turn. format: date-time daily_remaining: anyOf: - type: integer - type: 'null' title: Daily Remaining description: Test messages the account may still send today, shared with the test in the Talki apps. Resets at midnight in the account's `timezone`. `null` when it could not be read. tools_called: items: type: string type: array title: Tools Called description: 'The tools the assistant used to answer, in order, by the names it sees: Talki''s own (such as `check_availability`) and your app''s, as `__`.' type: object required: - session_id - reply - turn - max_turns - expires_at - daily_remaining - tools_called title: AgentTestReply description: The assistant's answer to one test message, and where the session stands. Send `session_id` with the next message before `expires_at`, at most `max_turns` turns in all. Appointment: properties: id: type: string title: Id description: Opaque Talki appointment identifier. location_id: type: string title: Location Id description: 'The location the booking is at (`GET /v1/locations`), the one its service belongs to. Never null, and it never changes: moving a booking keeps its location.' status: allOf: - $ref: '#/components/schemas/AppointmentStatus' description: '`active` or `cancelled`. A cancelled appointment is retained rather than deleted, and can be restored — expect to see an id return to `active` via `appointment.updated`.' client: $ref: '#/components/schemas/AppointmentClient' service: anyOf: - $ref: '#/components/schemas/ServiceRef' - type: 'null' description: The service booked. After the service is deleted it keeps its name with a null `id`. Null for an appointment taken without one (a generic slot), or whose service was deleted before Talki kept the name. start_at: type: string title: Start At description: Start of the booking, RFC 3339 UTC. format: date-time end_at: type: string title: End At description: End of the booking, RFC 3339 UTC. For a multi-day stay this is the check-out moment, so the span covers the whole booking rather than one night. format: date-time quantity: type: integer title: Quantity description: Party size the booking carries — covers, people, items — for a service that asks for one (`asks_quantity` on `GET /v1/services`). Always 1 for a service that does not, so you can read it unconditionally. It is the booking's total, not a breakdown per resource or unit. call_id: anyOf: - type: string - type: 'null' title: Call Id description: The call this booking was taken on, or null when it was not made on a call (entered in the Talki app or created through this API). notes: anyOf: - type: string - type: 'null' title: Notes description: 'The note on the booking, as the business sees it beside it: what `POST /v1/appointments` sent as `notes`, or what the assistant wrote on a booking taken on a call. Null when there is none.' created_at: type: string title: Created At description: When the booking was written, RFC 3339 UTC. format: date-time updated_at: type: string title: Updated At description: 'Last change to the booking, RFC 3339 UTC. Show it to a human as "last modified"; **do not sync on it**: changes do not become visible in `updated_at` order, so a watermark on it can skip a booking permanently. Use the change feed''s `next_cursor` instead.' format: date-time type: object required: - id - location_id - status - client - service - start_at - end_at - quantity - call_id - notes - created_at - updated_at title: Appointment description: 'One booking in the account''s calendar. This object is the record: a connected Google or Outlook calendar holds a copy, so reconcile against this object, not against the provider calendar.' AppointmentClient: properties: contact_id: anyOf: - type: string - type: 'null' title: Contact Id description: Talki contact whose number is `phone_number`, when there is one. Null otherwise. name: type: string title: Name description: First name the booking was taken under. surname: type: string title: Surname description: Surname the booking was taken under. phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: Client's number in E.164. Null when Talki has no number for the client, as on a booking taken on a call from a caller who withheld their number. type: object required: - contact_id - name - surname - phone_number title: AppointmentClient description: Who the booking is for. Always present; `contact_id` and `phone_number` are null when Talki has no number for the client. The name is the one the booking was taken under, exactly as the owner sees it, and may come from what the assistant heard on the call. AppointmentCreate: properties: service_id: anyOf: - type: string - type: 'null' title: Service Id description: The service being booked, from `GET /v1/services`. Null books a generic slot with no service attached — accepted, but it consumes no service capacity and the assistant cannot describe it to a caller, so prefer a real service. The booking is made at the service's location (`Service.location_id`), against that location's hours, closures and resources; without a service, at the main location (`is_default` on `GET /v1/locations`). A service of an inactive location is refused with 400 `location_inactive`. client_name: type: string maxLength: 100 minLength: 1 title: Client Name description: First name the booking is taken under. Required. client_surname: type: string maxLength: 100 minLength: 1 title: Client Surname description: Surname the booking is taken under. Required. client_phone_number: anyOf: - type: string - type: 'null' title: Client Phone Number description: Client's number. E.164 preferred; an Italian national number is normalised. A number that cannot be parsed is rejected. Null to leave it empty. start_at: type: string title: Start At description: Start of the booking, RFC 3339. Send UTC (`Z`) or an explicit offset; a timestamp without an offset is rejected. format: date-time end_at: anyOf: - type: string format: date-time - type: 'null' title: End At description: End of the booking, RFC 3339. Must be after `start_at`. For a service with a `duration_minutes`, omit it and Talki sets it from the duration; if sent, it must be exactly `start_at` plus the duration, or the booking is refused with 400 `invalid_parameter`. Required for a booking with no service. For a `day_range` service it is required and is the check-out moment — use the `end_at` of the window `GET /v1/availability` returned, which already carries the service's check-in and check-out times. quantity: type: integer minimum: 1.0 title: Quantity description: Party size, for a service whose `asks_quantity` is true. For a service that does not ask, it is forced to 1 without an error. For a service that asks, it must lie within the service's `min_quantity`/`max_quantity` (`GET /v1/services`), or the booking is refused with 400 `invalid_parameter`. Omitted means 1, which a service with `min_quantity` of 2 or more refuses. default: 1 notes: anyOf: - type: string maxLength: 2000 - type: 'null' title: Notes description: Customer-visible note on the booking, shown to the business alongside it. Null to leave it empty. type: object required: - client_name - client_surname - start_at title: AppointmentCreate description: 'A booking to create: one service per appointment, booked at that service''s location. `notes` is visible to the business and stored on the booking.' AppointmentList: properties: data: items: $ref: '#/components/schemas/Appointment' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 'Your position in the change feed after this page. Present on every page that returned data, including the last one — it is where you are, not a promise of more. Store it and pass it back as `cursor` to receive only what has changed since. Null only when the page was empty. Opaque: do not parse it, and do not use it on another endpoint.' has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: AppointmentList description: 'A page of the appointment change feed. `next_cursor` is your position in the feed: it is returned on every non-empty page, the last included, and an incremental sync resumes from it. Loop while `has_more` is true.' AppointmentReschedule: properties: client_name: anyOf: - type: string maxLength: 100 minLength: 1 - type: 'null' title: Client Name description: New first name, or null to leave it unchanged. client_surname: anyOf: - type: string maxLength: 100 minLength: 1 - type: 'null' title: Client Surname description: New surname, or null to leave it unchanged. client_phone_number: anyOf: - type: string - type: 'null' title: Client Phone Number description: New client number, E.164 preferred, or null to leave it unchanged. A number that cannot be parsed is rejected. start_at: anyOf: - type: string format: date-time - type: 'null' title: Start At description: New start, RFC 3339 with an offset. Null leaves it unchanged. end_at: anyOf: - type: string format: date-time - type: 'null' title: End At description: 'New end, RFC 3339 with an offset. Null leaves it unchanged — moving only `start_at` does NOT shift the end to preserve the duration, it moves one edge. Send both to move a booking. A booking of one service with a `duration_minutes` keeps that length, or the length it has now: a move that changes it is refused with 400 `invalid_parameter`.' type: object title: AppointmentReschedule description: A partial edit of a booking. Every field is optional, and an omitted field is left unchanged, not cleared. A move that does not fit is refused with a conflict code; nothing is booked. A booking never changes location. Availability: properties: service_id: type: string title: Service Id description: The service this availability is for. timezone: type: string title: Timezone description: IANA timezone the `date` fields are in. The same value `GET /v1/account` publishes. duration_minutes: anyOf: - type: integer - type: 'null' title: Duration Minutes description: Length of one booking of this service, repeated here so a consumer can slice an interval into offers without a second request. Null for a `day_range` service, where the length came from your own `stay_length`. quantity: type: integer title: Quantity description: The party size this answer was computed for. days: items: $ref: '#/components/schemas/AvailabilityDay' type: array title: Days description: One entry per local day in the requested range, in order. type: object required: - service_id - timezone - duration_minutes - quantity - days title: Availability description: 'When a service can be booked, over a range of days. Advisory, not a reservation: a window can be taken by a phone call a moment later, so a `409` from `POST /v1/appointments` after a clean lookup is normal. When the owner''s Google or Outlook calendar is connected, their events are subtracted, so this can be narrower than what a booking would accept, never wider.' AvailabilityDay: properties: date: type: string title: Date description: The local calendar date in the account's timezone, `YYYY-MM-DD`, not a UTC date. An interval shortly after local midnight starts on the previous UTC date. intervals: items: $ref: '#/components/schemas/AvailabilityInterval' type: array title: Intervals description: Bookable windows on this day, earliest first. Empty when none. closed: type: boolean title: Closed description: True when the business is shut for the whole day — a weekday with no working hours, or a closure the owner entered. Distinct from an open day that happens to be fully booked, where this is false and `intervals` is empty. type: object required: - date - intervals - closed title: AvailabilityDay description: One local calendar day of the requested range. Every day is present, closed and fully booked ones included. AvailabilityInterval: properties: start_at: type: string title: Start At description: Start of the bookable window, RFC 3339 UTC. format: date-time end_at: type: string title: End At description: End of the bookable window, RFC 3339 UTC. format: date-time type: object required: - start_at - end_at title: AvailabilityInterval description: 'A window a booking fits in, not a slot. For a `duration` service a booking may start anywhere from `start_at` to `end_at` minus the service''s `duration_minutes`; there is no start grid. For a `day_range` service the window is the stay you asked about: check-in to check-out, present only when that exact stay can be booked.' BlockedCallAttempt: properties: id: type: string title: Id description: Identifier of the attempt. location_id: type: string title: Location Id description: The location the call was for, whose rule refused it (`GET /v1/locations`). Never null. phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: The caller's number, E.164. label: anyOf: - type: string - type: 'null' title: Label description: The label of the rule that blocked it, or null once that rule is deleted. attempted_at: type: string title: Attempted At description: When the call came in, RFC 3339 UTC. format: date-time type: object required: - id - location_id - phone_number - label - attempted_at title: BlockedCallAttempt description: A call refused because its number is blocked. It has no `Call` record. BlockedCallAttemptList: properties: data: items: $ref: '#/components/schemas/BlockedCallAttempt' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: BlockedCallAttemptList description: A page of blocked calls, newest first. Loop while `has_more` is true. Call: properties: id: type: string title: Id description: '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`.' location_id: type: string title: Location Id description: '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.' caller: $ref: '#/components/schemas/CallCaller' started_at: type: string title: Started At description: When the call ARRIVED, before the assistant picked up. RFC 3339 UTC. This is the ordering key for `GET /v1/calls`. format: date-time answered_at: anyOf: - type: string format: date-time - type: 'null' title: Answered At description: When the assistant picked up. Null when the pickup time was not recorded. The gap from `started_at` is ring and connection-setup time, and is not billed. ended_at: anyOf: - type: string format: date-time - type: 'null' title: Ended At description: When the call was torn down. Null when the end time was not recorded; it is never derived from `duration_seconds`. duration_seconds: anyOf: - type: integer - type: 'null' title: Duration Seconds description: 'The billed duration in seconds, from `answered_at` to teardown: exactly what this call added to `GET /v1/usage` `used_seconds`, and to a billing partner''s usage report. Whole seconds, the fraction dropped; no minimum and no rounding up to the minute, so ten 6-second calls cost 60 seconds. A 0 bills nothing, and neither does any call on a developer sandbox. It excludes ring and connection-setup time, so it is a few seconds shorter than `ended_at - started_at`, and can differ from `ended_at - answered_at` by a second or so. It can also differ from a carrier''s own call timing. Null when the duration was not recorded.' summary: anyOf: - type: string - type: 'null' title: Summary description: 'Short natural-language summary of what the caller wanted, written by the assistant after the call. Null when none was produced. Not a transcript: the conversation itself is `GET /v1/calls/{id}/transcript`, under the separate `transcripts:read` scope.' appointment_ids: items: type: string type: array title: Appointment Ids description: 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. outcome: anyOf: - type: string - type: 'null' title: Outcome description: 'What the call came to, one value by priority, for a list column or a filter: `booked` (it booked an appointment, not cancelled again on the same call), `rescheduled` (it moved an existing appointment), `cancelled` (it cancelled one), `transferred` (a person took the call over), `unresolved` (it left a question for the owner), `info` (none of these). A call that did several things takes the first; the fields below say everything it did. Null on calls recorded before outcomes were tracked, where the three fields below are null too: unknown, not empty. New values may be added.' x-extensible-enum: - booked - rescheduled - cancelled - transferred - unresolved - info transfers: anyOf: - items: $ref: '#/components/schemas/CallTransfer' type: array - type: 'null' title: Transfers description: 'Every transfer to a person, in order: a caller can be passed on more than once. Empty when there was none.' appointment_changes: anyOf: - items: $ref: '#/components/schemas/CallAppointmentChange' type: array - type: 'null' title: Appointment Changes description: Existing appointments this call moved or cancelled, in order. Appointments it booked are `appointment_ids`, and a change to one of those is listed here too. unresolved_request_ids: anyOf: - items: type: string type: array - type: 'null' title: Unresolved Request Ids description: The questions this call left for the owner (`GET /v1/unresolved_requests/{id}`). Empty when there was none. created_at: type: string title: Created At description: '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.' format: date-time read_at: anyOf: - type: string format: date-time - type: 'null' title: Read At description: 'When the call was first marked read, RFC 3339 UTC. Null while unread. Inbox state: it changes with `PATCH /v1/calls/{id}` and in the Talki app, sends `call.updated`, and does not move the call in the `sync=true` feed.' archived_at: anyOf: - type: string format: date-time - type: 'null' title: Archived At description: When the call was archived, RFC 3339 UTC. Null while it is in the inbox. Archiving marks the call read; marking an archived call unread clears `read_at` and leaves it archived. Inbox state, like `read_at`. type: object required: - id - location_id - caller - started_at - answered_at - ended_at - duration_seconds - summary - appointment_ids - outcome - transfers - appointment_changes - unresolved_request_ids - created_at - read_at - archived_at title: Call description: One inbound call the assistant answered. Its record never changes after it is written, so it appears once in the change feed. Only its inbox state, `read_at` and `archived_at`, changes later, and `call.updated` reports that. A deleted call leaves the feed and the log; `call.deleted` is its only trace. CallAppointmentChange: properties: appointment_id: type: string title: Appointment Id description: The appointment. action: type: string title: Action description: '`rescheduled` or `cancelled`.' x-extensible-enum: - rescheduled - cancelled type: object required: - appointment_id - action title: CallAppointmentChange description: An existing appointment the call moved or cancelled. CallCaller: properties: contact_id: anyOf: - type: string - type: 'null' title: Contact Id description: Talki contact this number resolves to, or null if the account has no contact for it. Stable per (account, number). phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: Caller's number in E.164. Null when the CallerID was withheld. display_name: anyOf: - type: string - type: 'null' title: Display Name description: Contact name, only when the account owner entered it by hand or imported it from their own address book. Null otherwise, including when the only name available was heard on the call. type: object required: - contact_id - phone_number - display_name title: CallCaller description: 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. CallCount: properties: total: type: integer title: Total description: The number of calls. type: object required: - total title: CallCount description: A count of calls. CallList: properties: data: items: $ref: '#/components/schemas/Call' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque position after this page. In the default newest-first list this is a page pointer and is null on the last page. With `sync=true` it is your position in the change feed and is present on every page that returned data, including the last one — store it and pass it back as `cursor` to receive only what has been recorded since. An empty page answers null, so keep the cursor you hold; only a cursor issued up to 2026-11-04 gets its replacement there. Do not parse it, and do not use a cursor from one mode in the other. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: CallList description: 'A page of calls. In the default newest-first list, `next_cursor` points at the next page and is null after the last. With `sync=true` it is your position in the change feed, returned on the last page too: store it and resume from it.' CallStats: properties: period_days: type: integer title: Period Days description: 'How many days the period covers: `days`, or the days from `from` to `to`.' period_start: type: string title: Period Start description: Start of the period, RFC 3339 UTC, included. format: date-time period_end: type: string title: Period End description: 'End of the period, RFC 3339 UTC, excluded: now, or local midnight after `to`.' format: date-time total_calls: type: integer title: Total Calls description: Calls in the period. total_duration_seconds: type: integer title: Total Duration Seconds description: Their total talk time, as billed (`Call.duration_seconds`). average_duration_seconds: type: number title: Average Duration Seconds description: Their average talk time, to one decimal. 0 with no calls. booked_calls: type: integer title: Booked Calls description: Calls in the period that booked at least one appointment, counted once however many they booked, and still counted if the booking was cancelled since. unresolved_calls: type: integer title: Unresolved Calls description: 'Calls in the period that left at least one question the assistant could not answer (`GET /v1/unresolved_requests`), counted once however many they left, whatever the requests'' status now. A call may count here and in `booked_calls` both. Calls Talki refused are never in these figures: see `GET /v1/refused_calls/summary`.' transferred_calls: type: integer title: Transferred Calls description: Calls in the period the assistant transferred to a person, counted once however many transfers they had. Calls recorded before transfers were stored (see `Call.outcome`) are not counted, so a period reaching back before then undercounts. today: type: integer title: Today description: Calls since midnight today. this_week: type: integer title: This Week description: Calls since Monday. this_month: type: integer title: This Month description: Calls since the first of the month. daily: items: $ref: '#/components/schemas/CallStatsDay' type: array title: Daily description: One entry per day in the period that had calls, oldest first. top_callers: items: $ref: '#/components/schemas/CallStatsCaller' type: array title: Top Callers description: Up to ten numbers that called most in the period, most calls first. type: object required: - period_days - period_start - period_end - total_calls - total_duration_seconds - average_duration_seconds - booked_calls - unresolved_calls - transferred_calls - today - this_week - this_month - daily - top_callers title: CallStats description: Call figures over a period (the last `days`, or the local days `from` to `to`), plus today, this week and this month, in the account's `timezone`. CallStatsCaller: properties: phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: The caller's number, E.164. Null stands for every caller who withheld their number, counted as one. calls: type: integer title: Calls description: Calls from this number in the period. duration_seconds: type: integer title: Duration Seconds description: Their total talk time. last_call_at: type: string title: Last Call At description: When the latest of them started, RFC 3339 UTC. format: date-time type: object required: - phone_number - calls - duration_seconds - last_call_at title: CallStatsCaller description: One of the numbers that called most in the period. CallStatsDay: properties: date: type: string title: Date description: A local calendar day in the account's `timezone`, `YYYY-MM-DD`. calls: type: integer title: Calls description: Calls that started that day. duration_seconds: type: integer title: Duration Seconds description: Their total talk time. type: object required: - date - calls - duration_seconds title: CallStatsDay description: One day of the period's series. CallTranscript: properties: call_id: type: string title: Call Id description: The call this transcript belongs to. utterances: items: $ref: '#/components/schemas/TranscriptUtterance' type: array title: Utterances description: The turns, in the order they were spoken. source: type: string title: Source description: 'Which transcription pipeline produced the text. Today always `gemini_live_sidechannel`: transcribed live, during the call. Treat an unknown value as another automatic pipeline.' language_hint: anyOf: - type: string - type: 'null' title: Language Hint description: The language transcription was told to expect. `auto` means it followed the caller, who may switch language mid-call. assembler: type: integer title: Assembler description: Version of the code that cut the audio into turns. Rises when that changes, so two transcripts made differently can be told apart. created_at: type: string title: Created At description: When Talki stored this transcript, just after the call ended. RFC 3339 UTC. format: date-time type: object required: - call_id - utterances - source - language_hint - assembler - created_at title: CallTranscript description: The automatic transcript of one call. The text is machine-made and can be wrong, so show it as an automatic transcript, never as a verbatim record. It is deleted with its call, and when the account stops keeping transcripts; from then on this endpoint answers `transcript_not_available`. CallTransfer: properties: target_label: type: string title: Target Label description: The destination as the owner named it in Talki (e.g. `Reception`). Never the number behind it. Compare it case-insensitively. at: anyOf: - type: string format: date-time - type: 'null' title: At description: When the call was handed over, RFC 3339 UTC. type: object required: - target_label - at title: CallTransfer description: A hand-over of the call to a person, in the order it happened. CallUpdate: properties: read: title: Read description: '`true` marks the call read, keeping the first `read_at`. `false` marks it unread, archived or not. Cannot be null.' type: boolean archived: title: Archived description: '`true` archives the call and marks it read, whatever `read` says. `false` returns it to the inbox. Cannot be null.' type: boolean type: object title: CallUpdate description: Inbox state for one call. Send `read`, `archived` or both. CallerRule: properties: id: type: string title: Id description: Rule identifier. location_id: type: string title: Location Id description: The location whose calls it matches (`GET /v1/locations`). Never null, and it never changes. phone_number: type: string title: Phone Number description: The number, E.164. kind: allOf: - $ref: '#/components/schemas/CallerRuleKind' description: '`vip` or `blocked`.' label: anyOf: - type: string - type: 'null' title: Label description: The owner's name for it, or null. created_at: type: string title: Created At description: RFC 3339 UTC. format: date-time updated_at: type: string title: Updated At description: RFC 3339 UTC. format: date-time type: object required: - id - location_id - phone_number - kind - label - created_at - updated_at title: CallerRule description: A VIP or blocked number of one location. A number is on one list at most at a location, so adding it to the other list moves it. A call from a VIP number to its location rings with `caller.vip` true on `call.ringing`. CallerRuleCreate: properties: phone_number: type: string maxLength: 30 minLength: 1 title: Phone Number description: The number, E.164 or Italian national format. Stored as E.164. kind: allOf: - $ref: '#/components/schemas/CallerRuleKind' description: '`vip` (the default) or `blocked`.' default: vip label: anyOf: - type: string maxLength: 100 - type: 'null' title: Label description: The owner's name for it. type: object required: - phone_number title: CallerRuleCreate description: A number to add. `201` creates a rule; `200` means the number already had one, which was moved or relabelled as the request asks, or returned unchanged. CallerRuleList: properties: data: items: $ref: '#/components/schemas/CallerRule' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: CallerRuleList description: A page of caller rules, newest first. Loop while `has_more` is true. CallerRuleUpdate: properties: kind: title: Kind description: Move it to the other list. Cannot be null. $ref: '#/components/schemas/CallerRuleKind' label: anyOf: - type: string maxLength: 100 - type: 'null' title: Label description: Replaces the label. `null` or empty removes it. type: object title: CallerRuleUpdate description: A partial edit of a caller rule. Closure: properties: id: type: string title: Id description: Closure identifier. location_id: anyOf: - type: string - type: 'null' title: Location Id description: The one location it applies at (`GET /v1/locations`), or null when it applies at every location of the account. Set when it is created, and never changed. kind: allOf: - $ref: '#/components/schemas/ClosureKind' description: '`closed` — the business is shut, and no time is offered to callers. `open` — a special opening: extra hours on one day, offered to callers together with that day''s weekly hours. A closure on the same day still wins over both.' all_day: type: boolean title: All Day description: True for whole days, given by `start_date` and `end_date`; only a closure can be whole days. False for an exact range, given by `start_at` and `end_at`. start_date: anyOf: - type: string - type: 'null' title: Start Date description: First day, `YYYY-MM-DD`, when `all_day` is true. Null otherwise. end_date: anyOf: - type: string - type: 'null' title: End Date description: Last day, included, `YYYY-MM-DD`, when `all_day` is true. Null otherwise. start_at: type: string title: Start At description: Start, RFC 3339 UTC. For whole days this is midnight at the start of `start_date` in the account's `timezone`. format: date-time end_at: type: string title: End At description: End, exclusive, RFC 3339 UTC. For whole days this is midnight at the end of `end_date`. format: date-time reason: anyOf: - type: string - type: 'null' title: Reason description: Why, such as "ferie estive". The assistant can tell callers. Null when none was given. created_at: type: string title: Created At description: When it was added, RFC 3339 UTC. format: date-time type: object required: - id - location_id - kind - all_day - start_date - end_date - start_at - end_at - reason - created_at title: Closure description: 'A dated exception to `WorkingHours`: a closure (`kind: closed`), when the business takes no bookings, or a special opening (`kind: open`), extra hours on one day that are added to that day''s weekly hours. It applies at one location, or at every location when `location_id` is null. Appointments already inside a closure are not cancelled: look them up with `GET /v1/appointments` and `starts_after`/`starts_before`.' ClosureCreate: properties: kind: allOf: - $ref: '#/components/schemas/ClosureKind' description: '`closed` (the default) for a closure, `open` for a special opening. A special opening is always an exact range that starts and ends on the same day in the account''s `timezone`; it adds to that day''s weekly hours.' default: closed all_day: type: boolean title: All Day description: True to close whole days, given by `start_date` and `end_date`. False (the default) for an exact range, given by `start_at` and `end_at`. Only a closure can be whole days. default: false start_date: anyOf: - type: string - type: 'null' title: Start Date description: First closed day, `YYYY-MM-DD`. Required when `all_day` is true. end_date: anyOf: - type: string - type: 'null' title: End Date description: Last closed day, included, `YYYY-MM-DD`. Required when `all_day` is true. The same as `start_date` for a single day. start_at: anyOf: - type: string format: date-time - type: 'null' title: Start At description: Start of the closure or special opening, RFC 3339 with a UTC offset. Required when `all_day` is false. end_at: anyOf: - type: string format: date-time - type: 'null' title: End At description: End of the closure or special opening, exclusive, RFC 3339 with a UTC offset. Must be after `start_at`. Required when `all_day` is false. A special opening must end on the day it starts; midnight at the end of that day is allowed. reason: anyOf: - type: string maxLength: 500 - type: 'null' title: Reason description: Why the business is closed, or open specially. The assistant can tell callers. location_id: anyOf: - type: string - type: 'null' title: Location Id description: The one location it applies at, an id from `GET /v1/locations` (inactive ones included). Omit it, or send `null`, for a closure or special opening of every location of the account. Cannot be changed afterwards. type: object title: ClosureCreate description: 'A new closure or special opening: `all_day: true` with `start_date` and `end_date` (closures only), or an exact range with `start_at` and `end_at`. Sending fields of both forms is refused, and so is a special opening that does not start and end on the same day in the account''s `timezone`. Without `location_id`, it applies at every location.' ClosureList: properties: data: items: $ref: '#/components/schemas/Closure' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: ClosureList description: 'Every closure or special opening of the requested `kind` overlapping the requested days, earliest first, in one page: `next_cursor` is always null. With `location_id`, those of that location and those of every location.' ClosureUpdate: properties: kind: title: Kind description: '`closed` or `open`. Cannot be null. Turning a closure into a special opening needs a window that starts and ends on one day.' $ref: '#/components/schemas/ClosureKind' all_day: title: All Day description: Whole days or an exact range. Cannot be null. type: boolean start_date: anyOf: - type: string - type: 'null' title: Start Date description: First day, `YYYY-MM-DD`. end_date: anyOf: - type: string - type: 'null' title: End Date description: Last day, included, `YYYY-MM-DD`. start_at: anyOf: - type: string format: date-time - type: 'null' title: Start At description: Start, RFC 3339 with a UTC offset. end_at: anyOf: - type: string format: date-time - type: 'null' title: End At description: End, RFC 3339 with a UTC offset. Must be after `start_at`. reason: anyOf: - type: string maxLength: 500 - type: 'null' title: Reason description: Replaces the reason. Send `null` or an empty string to remove it. location_id: anyOf: - type: string - type: 'null' title: Location Id description: Cannot be changed. Accepted only when it is the closure's own `location_id` (`null` for one of every location), so a client may send the whole object back; any other value is refused with `invalid_parameter`. type: object title: ClosureUpdate description: A partial edit of a closure or special opening. To move it, send the whole new window in one of the two forms. It stays at the location it was created for. Contact: properties: id: type: string title: Id description: Opaque Talki contact identifier. phone_number: type: string title: Phone Number description: The contact's number in E.164. first_name: anyOf: - type: string - type: 'null' title: First Name description: Given name, or null. last_name: anyOf: - type: string - type: 'null' title: Last Name description: Family name, or null. display_name: anyOf: - type: string - type: 'null' title: Display Name description: First and last name joined, or null when both are absent. notes: anyOf: - type: string - type: 'null' title: Notes description: Notes the account owner wrote about this person. Customer-visible text, never the assistant's own notes. last_call_at: anyOf: - type: string format: date-time - type: 'null' title: Last Call At description: Most recent call from this number, RFC 3339 UTC, or null. call_count: anyOf: - type: integer - type: 'null' title: Call Count description: Calls received from this number, or null for an unverified contact returned by upsert. created_at: type: string title: Created At description: When the contact was added, RFC 3339 UTC. format: date-time updated_at: type: string title: Updated At description: 'Last change to the contact, RFC 3339 UTC. Show it to a human as "last modified"; **do not sync on it**: as with `Appointment.updated_at`, a watermark on it can skip a contact permanently. Resume with the change feed''s `next_cursor`.' format: date-time type: object required: - id - phone_number - first_name - last_name - display_name - notes - last_call_at - call_count - created_at - updated_at title: Contact description: A person in the account's address book. Only contacts the owner entered, imported or confirmed are published; names the assistant only heard are `PendingContact`s until the owner approves them. One contact per phone number; once stored, match on `id`. ContactList: properties: data: items: $ref: '#/components/schemas/Contact' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 'Your position in the change feed after this page. Present on every page that returned data, including the last one. Store it and pass it back as `cursor` to receive only what has changed since. Null only when the page was empty. Opaque: do not parse it, and do not use it on another endpoint. On a search (`phone` or `tag_id`), the cursor of the next page instead, null on the last one.' has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: ContactList description: A page of the contact change feed. `next_cursor` is your position, returned on the last page too; resume an incremental sync from it. With `phone` or `tag_id`, a page of a search instead, newest contact first, whose `next_cursor` is null on the last page. ContactUpsert: properties: phone_number: type: string title: Phone Number description: The contact's number. E.164 preferred; an Italian national number is normalised. A number that cannot be parsed is rejected. first_name: anyOf: - type: string maxLength: 100 - type: 'null' title: First Name description: Given name, or null. last_name: anyOf: - type: string maxLength: 100 - type: 'null' title: Last Name description: Family name, or null. notes: anyOf: - type: string maxLength: 2000 - type: 'null' title: Notes description: Customer-visible notes about this person, returned as `Contact.notes`. external_id: anyOf: - type: string maxLength: 255 - type: 'null' title: External Id description: Your own id for this person. Stored as a cross-reference, unique per (account, system, id). Supply it and a later upsert finds the same contact even if the phone number changed. system: anyOf: - type: string maxLength: 64 - type: 'null' title: System description: Which system `external_id` belongs to, e.g. your product's name. Required when `external_id` is given; ignored otherwise. type: object required: - phone_number title: ContactUpsert description: 'Create or update the contact with this phone number: the number is the identity, and `external_id` is your cross-reference for finding it again after a number changes. A name written here is not overwritten by what the assistant hears on later calls. On a contact whose name was only guessed from a call, sending either name replaces both: the one you omit is cleared.' Document: properties: id: type: string title: Id description: Document identifier. location_id: type: string title: Location Id description: The location whose assistant uses it (`GET /v1/locations`). Never null, and it never changes. title: type: string title: Title description: The note's title, the uploaded file's name, or the imported site's address. source: type: string enum: - text - file - website title: Source description: '`text` for a note written as text, `file` for an uploaded file, `website` for pages imported from a site.' mime_type: type: string title: Mime Type description: 'The content type: `text/markdown` for a note, the file''s type for a file, `text/html` for a website.' size_bytes: type: integer title: Size Bytes description: 'What it counts against the account''s knowledge storage: the note''s text, the file as uploaded, or the text extracted from the site. 0 for an upload that failed holding nothing.' chunk_count: type: integer title: Chunk Count description: How many passages its content is searched as. While it is `processing`, the count of the content it still answers with; for a new document, 0 until its content has been read. A new copy may show its count from the start. file_available: type: boolean title: File Available description: 'True when the uploaded file is kept and `GET /v1/documents/{document_id}/file` returns it: shortly after the file is first `ready`, later for a copy at another location. False for a note, a website, a file whose first upload is not `ready` yet or `failed`, and a file Talki did not keep. A file being replaced keeps its previous file until the new one has been read, then has none until shortly after the new version is `ready`.' status: type: string enum: - processing - ready - failed title: Status description: '`processing` while its latest content is being read and indexed, `ready` once the assistant uses it, `failed` when its latest content could not be indexed (`status_error` says why). A document that was ready before keeps answering with its previous content while `processing` and after `failed`.' status_error: anyOf: - type: string - type: 'null' title: Status Error description: Why its latest content could not be indexed. Null unless `status` is `failed`. enabled: type: boolean title: Enabled description: 'False when it is switched off: kept, but the assistant does not use it until it is switched on again.' faq: type: boolean title: Faq description: True for the location's FAQ note, which the answers taught with `POST /v1/unresolved_requests/{request_id}/teach` are added to. A location has one at most. copy_group_id: anyOf: - type: string - type: 'null' title: Copy Group Id description: Shared by the copies of this document at other locations; null for a document that was never copied. created_at: type: string title: Created At description: RFC 3339 UTC. format: date-time updated_at: type: string title: Updated At description: 'When its title or content was last written, RFC 3339 UTC: a note''s text or title when it is saved, a file''s title when it is renamed, and a replaced file''s or a website''s new content, a dropped page included, when it is `ready`. Sending the same text, file or pages again counts as a write; switching it on or off does not.' format: date-time type: object required: - id - location_id - title - source - mime_type - size_bytes - chunk_count - file_available - status - status_error - enabled - faq - copy_group_id - created_at - updated_at title: Document description: 'A document of the knowledge base the assistant answers callers from: a text note, an uploaded file or an imported website, at one location. Its copies at other locations are documents of their own, sharing `copy_group_id`. It is used once `status` is `ready`; a document whose content is replaced answers with its previous content until then.' DocumentDiscover: properties: url: type: string maxLength: 2048 minLength: 1 title: Url description: The site's address, http or https. additionalProperties: false type: object required: - url title: DocumentDiscover description: A site to look for pages in before importing it. DocumentDiscovery: properties: url: type: string title: Url description: The address looked at. pages: items: type: string type: array title: Pages description: The site's pages found from its sitemap or its links, the address itself first. max_pages: anyOf: - type: integer - type: 'null' title: Max Pages description: How many pages one import may read on the account's plan; null when there is no limit. type: object required: - url - pages - max_pages title: DocumentDiscovery description: The pages found on a site, to choose the `pages` of an import from, and how many one import may read on the account's plan. DocumentList: properties: data: items: $ref: '#/components/schemas/Document' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: DocumentList description: A page of documents, newest first. Loop while `has_more` is true. DocumentPage: properties: id: type: string title: Id description: Page identifier. url: type: string title: Url description: The page's address. title: anyOf: - type: string - type: 'null' title: Title description: The page's title, when it has one. status: type: string enum: - ok - thin - blocked - failed title: Status description: '`ok` when it was read, `thin` when it was read but holds little text, `blocked` when the site refused it (bot protection), `failed` when it could not be read. Only `ok` and `thin` pages are searched.' char_count: type: integer title: Char Count description: Characters of text read from it. crawled_at: anyOf: - type: string format: date-time - type: 'null' title: Crawled At description: When it was read, RFC 3339 UTC. type: object required: - id - url - title - status - char_count - crawled_at title: DocumentPage description: One page of an imported website, and whether it was read. DocumentPageList: properties: data: items: $ref: '#/components/schemas/DocumentPage' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: DocumentPageList description: 'Every page of an imported website, in the order they were read. Never more than one page of results: `has_more` is always false.' DocumentText: properties: document_id: type: string title: Document Id description: The document's identifier. text: type: string title: Text description: 'A note''s text as last written, even while it is `processing`. For a file or a website, the text read from it, as the assistant searches it: the passages in order, separated by a blank line, and empty until it is first `ready`.' type: object required: - document_id - text title: DocumentText description: 'The text the assistant reads from a document: a note''s text as written, or what Talki read from a file or a website, as the assistant searches it. Consecutive passages may repeat a few words where they overlap.' DocumentUpdate: properties: title: title: Title description: Its new title. Not for a website, whose title is its address. A note's new title is indexed again, as a change of its text is. type: string maxLength: 200 minLength: 1 enabled: title: Enabled description: Switch it off (`false`) or on again (`true`). Cannot be null. type: boolean additionalProperties: false type: object title: DocumentUpdate description: 'A partial edit of a document: its title, or whether the assistant uses it.' FakeCallRequest: properties: scenario: type: string title: Scenario description: One of the keys from `GET /v1/sandbox/scenarios`. caller_phone: type: string maxLength: 20 minLength: 1 title: Caller Phone description: The number the fake call came from. Reuse one across calls to build a caller with history; vary it to exercise the first-time path. At most 20 characters. default: '+393480000001' type: object required: - scenario title: FakeCallRequest description: The call a sandbox should pretend it had. FakeCallResponse: properties: call_id: type: string title: Call Id description: The Call this fake call produced — fetchable at `GET /v1/calls/{id}`, and the same id the `call.ended` delivery carries in `data.object.id` and the `call.ringing` delivery before it in `data.call_id`. scenario: type: string title: Scenario caller_phone: type: string title: Caller Phone started_at: type: string format: date-time title: Started At ended_at: type: string format: date-time title: Ended At duration_seconds: type: integer title: Duration Seconds appointment_id: anyOf: - type: string - type: 'null' title: Appointment Id description: The appointment this call created, moved or cancelled, if any. events: items: type: string type: array title: Events description: 'The scenario''s event types, each sent by this call. A pending contact it proposed sends its own event too, not listed here. Every delivery carries `livemode: false`.' type: object required: - call_id - scenario - caller_phone - started_at - ended_at - duration_seconds - appointment_id - events title: FakeCallResponse description: The call that was recorded, and the webhook events it sent. ForwardingCheck: properties: location_id: type: string title: Location Id description: 'The location whose line is checked, an id from `GET /v1/locations`: the one the request named with `location_id`, or the main location when it named none.' status: type: string enum: - idle - pending - verified - not_detected title: Status description: '`pending` while the check call is ringing, at most about a minute. `verified` when the call came back through forwarding, `not_detected` when it did not. Either result is kept for ten minutes, then the status returns to `idle`.' reason: anyOf: - type: string - type: 'null' title: Reason description: When `status` is `verified`, the forwarding condition the carrier reported, such as `unconditional`, `user-busy`, `no-answer` or `unavailable`. Null otherwise, or when the carrier reported none. verified_at: anyOf: - type: string format: date-time - type: 'null' title: Verified At description: When `status` is `verified`, when the call came back, RFC 3339 UTC. Null otherwise. last_verified_at: anyOf: - type: string format: date-time - type: 'null' title: Last Verified At description: The most recent time any check succeeded, RFC 3339 UTC, kept after `status` returns to `idle`. Null if no check has ever succeeded. type: object required: - location_id - status - reason - verified_at - last_verified_at title: ForwardingCheck description: 'The latest forwarding check of one location''s line, the main one unless `?location_id=` names another. Poll `GET /v1/forwarding_check` every few seconds after starting one, with the same `location_id`: `pending` turns into `verified` or `not_detected` within about a minute.' Location: properties: id: type: string title: Id description: Opaque Talki location identifier. name: type: string title: Name description: 'What the business calls the location; what the assistant names it to callers. Unique among active locations, not among all of them: key on `id`.' is_default: type: boolean title: Is Default description: True for the main location, exactly one per account. It is never switched off. status: type: string enum: - active - inactive title: Status description: '`active` — it answers its calls and takes bookings. `inactive` — switched off in Talki, by the owner or because the plan has room for fewer locations: its records stay, it takes no calls or bookings, and it has no Talki number.' phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: The Talki number that answers this location's calls, E.164. For the main location, the account's `phone_number`. Null while inactive, and while none is assigned. line: $ref: '#/components/schemas/LocationLine' description: The location's Talki number, its line that forwards to it, and whether that forwarding has been proven. For the main location, the same as `Account.line`. position: type: integer title: Position description: The owner's display order, lowest first. Not unique. created_at: type: string title: Created At description: When the location was added, RFC 3339 UTC. format: date-time deactivated_at: anyOf: - type: string format: date-time - type: 'null' title: Deactivated At description: When it was last switched off, RFC 3339 UTC. Null while active. type: object required: - id - name - is_default - status - phone_number - line - position - created_at - deactivated_at title: Location description: One place the business works from, with its own Talki number, assistant settings, weekly hours, line, services, resources and bookings. Every account has exactly one main location (`is_default`). Locations are created, renamed and switched off in Talki only; an inactive one stays listed with its records, takes no calls or bookings and has no Talki number. LocationLine: properties: phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: The location's Talki number, E.164; the same as `Location.phone_number`. forwarding_number: anyOf: - type: string - type: 'null' title: Forwarding Number description: The location's own line, which forwards its calls to `phone_number`, E.164. For the main location, the account's `forwarding_number`. Null when not set. status: allOf: - $ref: '#/components/schemas/LineStatus' description: '`no_number` while the location has no Talki number. `unverified` until a forwarding check of the current `forwarding_number` has succeeded, including while none is set. `verified` once one has; it proves forwarding was on at `verified_at`, not that it still is. Changing `forwarding_number` returns it to `unverified`.' verified_at: anyOf: - type: string format: date-time - type: 'null' title: Verified At description: When a forwarding check of the current `forwarding_number` last succeeded, RFC 3339 UTC. Null unless `status` is `verified`. type: object required: - phone_number - forwarding_number - status - verified_at title: LocationLine description: 'How a location''s calls reach Talki: its own line forwards to its Talki number. For the main location, the same values as `Account.line`.' LocationList: properties: data: items: $ref: '#/components/schemas/Location' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: LocationList description: 'Every location of the account, inactive ones included, active first and then in the owner''s order, in one page: `next_cursor` is always null.' MarkAllReadResult: properties: updated: type: integer title: Updated description: How many calls were marked read. Each one sends `call.updated`. type: object required: - updated title: MarkAllReadResult description: How many unread calls in the inbox were marked read. PendingContact: properties: id: type: string title: Id description: Identifier of the candidate. phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: 'The caller''s number, E.164. Null when the caller withheld it: such a candidate cannot be approved, only discarded.' first_name: anyOf: - type: string - type: 'null' title: First Name description: The given name heard, or null. last_name: anyOf: - type: string - type: 'null' title: Last Name description: The family name heard, or null. call_id: anyOf: - type: string - type: 'null' title: Call Id description: The call it was heard on, or null once that call has aged out. created_at: type: string title: Created At description: When it was first heard, RFC 3339 UTC. format: date-time type: object required: - id - phone_number - first_name - last_name - call_id - created_at title: PendingContact description: 'A name the assistant heard on a call, waiting for the owner. It is not a contact and must not be stored as one: approve it to make it a contact, or discard it.' PendingContactApproval: properties: first_name: anyOf: - type: string maxLength: 100 - type: 'null' title: First Name description: The given name to store. `null` or empty removes it. last_name: anyOf: - type: string maxLength: 100 - type: 'null' title: Last Name description: The family name to store. `null` or empty removes it. notes: anyOf: - type: string maxLength: 5000 - type: 'null' title: Notes description: 'Notes to store on the contact, returned as `Contact.notes`. `null` or empty removes them. Omitted: a new contact has none, and an existing one keeps its own.' type: object title: PendingContactApproval description: Corrections to apply while approving; omitted fields keep what was heard. PendingContactList: properties: data: items: $ref: '#/components/schemas/PendingContact' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: PendingContactList description: 'Every pending contact, newest first, in one page: `next_cursor` is always null.' RefusedCall: properties: id: type: string title: Id description: Opaque identifier of the attempt. location_id: type: string title: Location Id description: 'The location the call was for: the one `dialled_number` answered for when it rang, while the account held it or when it released it; the main location for the account''s own number, or one it has no claim on any more. Never null.' caller: $ref: '#/components/schemas/CallCaller' dialled_number: anyOf: - type: string - type: 'null' title: Dialled Number description: The Talki number that was called, E.164. It may be a number the account no longer holds, while the business's line still forwards to it. reason: type: string title: Reason description: 'Why the call was refused: `user_concurrency` (the plan''s simultaneous calls in use); `minutes` (talk time used up); `entitlement` (no active subscription); `trial_suspended` (the free trial was suspended); `suspended` (the service was suspended by the partner that manages the account); `deletion_pending` (the account is scheduled for deletion); `no_user` (the number no longer belongs to the account); `platform_concurrency` (Talki at capacity). New reasons may be added: show an unknown one as a generic refusal.' x-extensible-enum: - user_concurrency - minutes - entitlement - trial_suspended - suspended - deletion_pending - no_user - platform_concurrency action: anyOf: - type: string - type: 'null' title: Action description: 'What the business can do about it: `cancel_deletion` (for `deletion_pending`); `check_forwarding` (for `no_user`); `reactivate_subscription` (for `entitlement`, `trial_suspended`, `suspended`); `upgrade_plan` (for `user_concurrency`, `minutes`). Null when there is nothing it can do. New actions may be added.' x-extensible-enum: - cancel_deletion - check_forwarding - reactivate_subscription - upgrade_plan attempted_at: type: string title: Attempted At description: When the call came in, RFC 3339 UTC. format: date-time type: object required: - id - location_id - caller - dialled_number - reason - action - attempted_at title: RefusedCall description: A call Talki refused before answering. It has no `Call` record; `action` says what the business can do about it. RefusedCallList: properties: data: items: $ref: '#/components/schemas/RefusedCall' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: RefusedCallList description: A page of refused calls, newest first. Loop while `has_more` is true. RefusedCallSummary: properties: period_days: type: integer title: Period Days description: 'How many days the period covers: `days`, or the days from `from` to `to`.' period_start: type: string title: Period Start description: Start of the period, RFC 3339 UTC, included. format: date-time period_end: type: string title: Period End description: 'End of the period, RFC 3339 UTC, excluded: now, or local midnight after `to`.' format: date-time total: type: integer title: Total description: Refused calls in the period. by_reason: additionalProperties: type: integer propertyNames: x-extensible-enum: - user_concurrency - minutes - entitlement - trial_suspended - suspended - deletion_pending - no_user - platform_concurrency type: object title: By Reason description: Refused calls in the period per `reason` (the values listed on `RefusedCall.reason`). Reasons with none are omitted. recent: type: integer title: Recent description: Refused calls in the last `recent_days` days. recent_days: type: integer title: Recent Days description: The window `recent` counts, in days. actions: items: type: string x-extensible-enum: - cancel_deletion - check_forwarding - reactivate_subscription - upgrade_plan type: array title: Actions description: Every `action` the period's refusals call for, sorted, without duplicates (the values listed on `RefusedCall.action`). type: object required: - period_days - period_start - period_end - total - by_reason - recent - recent_days - actions title: RefusedCallSummary description: Refused calls over a period (the last `days`, or the local days `from` to `to`), by reason. ResetResponse: properties: seed: type: integer title: Seed description: The fixed seed this history was generated from. calls: type: integer title: Calls appointments: type: integer title: Appointments contacts: type: integer title: Contacts open_unresolved: type: integer title: Open Unresolved type: object required: - seed - calls - appointments - contacts - open_unresolved title: ResetResponse description: What the sandbox holds after a reset. Resource: properties: id: type: string title: Id description: Opaque Talki resource identifier. location_id: type: string title: Location Id description: 'The location it is at (`GET /v1/locations`). Capacity is physical: only services of the same location draw on it. Never null, and it never changes.' name: type: string title: Name description: What the business calls this resource. mode: type: string enum: - shared - units title: Mode description: '`shared` — one fungible pool of `capacity` units (covers, seats, slots). `units` — a set of discrete sized units, described by `unit_classes`.' capacity: type: integer title: Capacity description: In `shared` mode, the total units available at one time. In `units` mode this is the size of the LARGEST SINGLE unit, not a total — a resource with six four-tops reports 4. Use `max_party_size` for the question you probably mean. max_party_size: type: integer title: Max Party Size description: The largest single booking this resource can hold at one time, in its own units, before any service's `rate` is applied. Equals `capacity` in `shared` mode; in `units` mode it is derived from the classes and the combining rules, so six combinable four-tops report more than 4. A booking above this is refused with `party_too_large`. combine_across_classes: type: boolean title: Combine Across Classes description: True when a single booking may join units of DIFFERENT classes (a four-top plus a two-top for six). Per-class `combinable` still governs whether a class may be joined at all. Always false for a `shared` resource. unit_classes: items: $ref: '#/components/schemas/ResourceUnitClass' type: array title: Unit Classes description: The discrete units this resource is made of. Always empty for a `shared` resource. services: items: $ref: '#/components/schemas/ResourceServiceLink' type: array title: Services description: Which services draw on this resource, and at what rate. Empty means no service currently books against it, which makes it inert rather than unlimited. owner_service_id: anyOf: - type: string - type: 'null' title: Owner Service Id description: 'Set when this resource exists only for one service and is created, renamed and deleted with it: a service given its own limit (`initial_capacity`) gets one. Cleared as soon as a second service links to it, at which point the resource is shared and independent. Null for the default resource and for a resource the business created itself. Use it to tell a real shared resource (''this salon has three chairs'') from a per-service cap (''haircuts at a time'').' is_default: type: boolean title: Is Default description: 'True for a location''s default resource: the shared limit new duration services of that location draw on unless they are given their own or other resources, such as the salon''s chairs. At most one per location.' created_at: type: string title: Created At description: RFC 3339 UTC. format: date-time updated_at: type: string title: Updated At description: RFC 3339 UTC. Moves when the resource, any of its unit classes, or any of its service links changes. format: date-time type: object required: - id - location_id - name - mode - capacity - max_party_size - combine_across_classes - unit_classes - services - owner_service_id - is_default - created_at - updated_at title: Resource description: 'Something finite the business books against: tables, rooms, chairs, seats. Its unit classes and service links are included, and a change to either moves this resource in the change feed and sends `resource.updated`. A deleted resource leaves the feed; `resource.deleted` announces it. `capacity` means different things in the two modes; read the field descriptions before using it.' ResourceCreate: properties: name: type: string maxLength: 100 minLength: 1 title: Name description: What the business calls this resource. capacity: type: integer maximum: 1000.0 minimum: 1.0 title: Capacity description: Total units available at one time. service_ids: anyOf: - items: type: string type: array maxItems: 20 - type: 'null' title: Service Ids description: 'Existing services that draw on this resource, one unit per booking. A linked service keeps any other resource it already draws on: a booking must fit all of them.' type: object required: - name - capacity title: ResourceCreate description: 'A new `shared` resource at one location: a count of interchangeable units, optionally drawn on by existing services of that location. With no `service_ids` it limits nothing until a service is linked to it, for example by `POST /v1/services` with `resource_ids`. Resources made of sized units are set up in Talki.' ResourceList: properties: data: items: $ref: '#/components/schemas/Resource' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 'Your position in the change feed after this page. Present on every page that returned data, including the last one. Store it and pass it back as `cursor` to receive only what has changed since. Null only when the page was empty. Opaque: do not parse it, and do not use it on another endpoint.' has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: ResourceList description: A page of the resource change feed, oldest change first. ResourceServiceLink: properties: service_id: type: string title: Service Id description: Opaque identifier of a service in `GET /v1/services`. rate: type: integer title: Rate description: Units of this resource consumed per booked unit of the service. A booking of quantity q consumes `q * rate`. Usually 1; a service that occupies two stations at once has 2. type: object required: - service_id - rate title: ResourceServiceLink description: A service that draws on this resource, and how much of it one booking takes. ResourceUnitClass: properties: id: type: string title: Id description: Opaque identifier for this class of units. name: type: string title: Name description: What the business calls these units. size: type: integer title: Size description: How much one unit of this class holds — covers at a table, people in a room, always 1 for a single-occupancy station. count: type: integer title: Count description: How many identical units of this size exist. combinable: type: boolean title: Combinable description: True when several units of this class may be joined to hold one oversized booking (two four-tops pushed together for six). combine_max: anyOf: - type: integer - type: 'null' title: Combine Max description: Largest number of units of this class one booking may join. Null means as many as exist. Meaningless when `combinable` is false. type: object required: - id - name - size - count - combinable - combine_max title: ResourceUnitClass description: '`count` identical units that each hold `size` — six four-seat tables, two rooms that sleep four. Units have no individual identity: you can see how many exist, not which are taken.' ResourceUpdate: properties: name: anyOf: - type: string maxLength: 100 minLength: 1 - type: 'null' title: Name description: What the business calls this resource. capacity: anyOf: - type: integer maximum: 1000.0 minimum: 1.0 - type: 'null' title: Capacity description: 'Total units available at one time. Accepted only on a `shared` resource: in `units` mode capacity is derived from the unit classes, which are not writable through this API.' type: object title: ResourceUpdate description: The two fields you can change on a resource. A capacity below what is already booked is refused. ScenarioSummary: properties: key: type: string title: Key description: The value to pass as `scenario`. description: type: string title: Description description: What the caller did on this call. events: items: type: string type: array title: Events description: 'The webhook event types this scenario is about: each is sent, so an integration test can assert that they arrive. Other events can come too: a caller who gives a name is proposed as a contact, as on a real call, which sends `pending_contact.created` when the number has no contact or pending contact yet.' duration_seconds: type: integer title: Duration Seconds type: object required: - key - description - events - duration_seconds title: ScenarioSummary description: One sandbox call scenario, and the events it emits. Service: properties: id: type: string title: Id description: Opaque Talki service identifier. location_id: type: string title: Location Id description: The location that offers it (`GET /v1/locations`). Each location has services of its own, so two locations selling the same thing have one service each, with its own id, price and availability. Never null, and it never changes. name: type: string title: Name description: What the business calls this service. description: anyOf: - type: string - type: 'null' title: Description description: Longer description shown to a customer, or null. price: anyOf: - type: string - type: 'null' title: Price description: 'Price as the owner wrote it: free text, not a number, such as "25€", "from 25€" or "price on request", usually in Italian. Do not parse it into a currency amount; render it as-is. Null when no price is published.' duration_minutes: anyOf: - type: integer - type: 'null' title: Duration Minutes description: How long one booking of this service lasts, in minutes. Null when `booking_mode` is `day_range` — a stay is measured in nights or days, not minutes — and null for a service with no fixed length. booking_mode: type: string enum: - duration - day_range title: Booking Mode description: '`duration` for a timed slot (the common case), or `day_range` for a stay spanning whole nights or days: a hotel room, a multi-day rental. Read this before `duration_minutes`; the two modes are booked with different information.' range_unit: anyOf: - $ref: '#/components/schemas/RangeUnit' - type: 'null' title: Range Unit description: '`nights` (check-out day is free again) or `days` (the whole last day is held). Only set when `booking_mode` is `day_range`, null otherwise.' min_stay: anyOf: - type: integer - type: 'null' title: Min Stay description: Shortest stay accepted, in `range_unit` units. Null = no floor. max_stay: anyOf: - type: integer - type: 'null' title: Max Stay description: Longest stay accepted, in `range_unit` units. Null = no cap. checkin_time: anyOf: - type: string - type: 'null' title: Checkin Time description: 'Local check-in time as `HH:MM`, for a `day_range` service. Wall-clock time in the account''s timezone (`GET /v1/account`), not UTC and not an instant: it is the same on every date, across daylight-saving changes.' checkout_time: anyOf: - type: string - type: 'null' title: Checkout Time description: Local check-out time as `HH:MM`. Same rules as `checkin_time`. asks_quantity: type: boolean title: Asks Quantity description: True when a booking of this service carries a count — covers, people, items — and the assistant asks for it. False when one booking always means one unit. quantity_label: anyOf: - type: string - type: 'null' title: Quantity Label description: What that count is called, in the business's own words and language (for example "people" or "covers", usually in Italian). Null when `asks_quantity` is false, or when the owner left it unnamed. min_quantity: type: integer title: Min Quantity description: Smallest count a booking may carry. max_quantity: anyOf: - type: integer - type: 'null' title: Max Quantity description: Largest count a booking may carry. Null = no per-booking cap. is_active: type: boolean title: Is Active description: False when the business has switched the service off. It is still published — see the note on this object — but it is not bookable and should not be offered. created_at: type: string title: Created At description: When the service was added, RFC 3339 UTC. format: date-time updated_at: type: string title: Updated At description: Last change to the service, RFC 3339 UTC. Show it to a human; **do not sync on it**, for the reason given on `Appointment.updated_at`. format: date-time type: object required: - id - location_id - name - description - price - duration_minutes - booking_mode - range_unit - min_stay - max_stay - checkin_time - checkout_time - asks_quantity - quantity_label - min_quantity - max_quantity - is_active - created_at - updated_at title: Service description: 'One bookable thing the business offers. Capacity is published on `Resource`, not here; `Resource.services` links the two. Inactive services stay in the feed: filter on `is_active` for a snapshot, never while syncing. A deleted service leaves the feed; `service.deleted` announces it, with the service as it was. Without the events, reconcile deletions with a full walk from no cursor.' ServiceCreate: properties: name: type: string maxLength: 100 minLength: 1 title: Name description: What the business calls this service. description: anyOf: - type: string maxLength: 2000 - type: 'null' title: Description description: Longer customer-facing description. price: anyOf: - type: string maxLength: 50 - type: 'null' title: Price description: Price as free text, the way the owner writes it, such as "25€" or "from 25€". Stored as sent. duration_minutes: type: integer maximum: 480.0 minimum: 5.0 title: Duration Minutes description: Length of one booking, in minutes. initial_capacity: anyOf: - type: integer maximum: 100.0 minimum: 1.0 - type: 'null' title: Initial Capacity description: How many bookings of this service can overlap, counting only its own. Talki creates a resource of that capacity for this service alone. Omit it to share the location's default resource, or when sending `resource_ids`. resource_ids: anyOf: - items: type: string type: array maxItems: 20 minItems: 1 - type: 'null' title: Resource Ids description: Existing resources this service draws on, one unit of each per booking. A booking must fit every one of them. A resource that until now belonged to one other service alone becomes a shared resource. Omit it when sending `initial_capacity`, or to share the location's default resource. type: object required: - name - duration_minutes title: ServiceCreate description: A new service with a fixed duration at one location, bookable at once. Send at most one of `initial_capacity`, which gives the service a resource of its own, or `resource_ids`, which makes it draw on resources of the same location. With neither, it draws on the location's default resource (`is_default`); a location with no default resource yet is refused with `400 invalid_parameter`. Services booked by the day or night, party sizes, buffers and exclusions are set up in Talki. ServiceList: properties: data: items: $ref: '#/components/schemas/Service' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 'Your position in the change feed after this page. Present on every page that returned data, including the last one. Store it and pass it back as `cursor` to receive only what has changed since. Null only when the page was empty. Opaque: do not parse it, and do not use it on another endpoint.' has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: ServiceList description: A page of the service change feed. `next_cursor` is your position, returned on the last page too. ServiceRef: properties: id: anyOf: - type: string - type: 'null' title: Id description: 'Opaque Talki service identifier. Null once the service has been deleted: the appointment survives, the reference does not.' name: anyOf: - type: string - type: 'null' title: Name description: The service's current name or, once the service has been deleted, the name it had when the appointment was booked. type: object required: - id - name title: ServiceRef description: The service an appointment is for, with enough to display it. Once the service is deleted, `id` is null and `name` is the one it was booked under. Fetch the full service with `services:read`. ServiceUpdate: properties: name: title: Name description: What the business calls this service. type: string maxLength: 100 minLength: 1 description: anyOf: - type: string maxLength: 2000 - type: 'null' title: Description description: Longer customer-facing description. price: anyOf: - type: string maxLength: 50 - type: 'null' title: Price description: 'Price as free text, the way the owner writes it, such as "25€", "from 25€" or "price on request". Stored as sent: not parsed, not validated as a number, and not a currency amount.' duration_minutes: title: Duration Minutes description: 'Length of one booking, in minutes. Rejected for a `day_range` service, whose length is measured in nights or days. Cannot be null: a service with no length is not bookable, and switching one off is `is_active: false`.' type: integer maximum: 480.0 minimum: 5.0 is_active: title: Is Active description: 'Switch the service off or on. An inactive service cannot be booked, by you or by the assistant, but still appears in `GET /v1/services` with `is_active: false`.' type: boolean type: object title: ServiceUpdate description: The service fields you can change. Every field is optional; an omitted one is left unchanged. Everything else on a service — booking mode, stay rules, quantities, capacity — is read-only here. Tag: properties: id: type: string title: Id description: Tag identifier. name: type: string title: Name description: The label, as shown to the owner. color: type: string title: Color description: The display colour, as the Talki app stores it. contact_ids: items: type: string type: array title: Contact Ids description: The contacts that carry this tag, as `GET /v1/contacts` ids, sorted. created_at: type: string title: Created At description: When the tag was made, RFC 3339 UTC. format: date-time type: object required: - id - name - color - contact_ids - created_at title: Tag description: A label on contacts. `contact_ids` are ids from `GET /v1/contacts`; `tag.updated` reports a change to the label or to who carries it, including a contact deleted or tagged in the Talki app. TagCreate: properties: name: type: string maxLength: 100 minLength: 1 title: Name description: The label. Leading and trailing spaces are removed. color: type: string maxLength: 20 minLength: 1 title: Color description: The display colour, such as `#e0867a`. type: object required: - name - color title: TagCreate description: A new tag. An account holds at most 50. TagList: properties: data: items: $ref: '#/components/schemas/Tag' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: TagList description: 'Every tag, newest first, in one page: `next_cursor` is always null.' TagUpdate: properties: name: anyOf: - type: string maxLength: 100 minLength: 1 - type: 'null' title: Name description: The label. color: anyOf: - type: string maxLength: 20 minLength: 1 - type: 'null' title: Color description: The display colour. type: object title: TagUpdate description: A partial edit of a tag. TranscriptUtterance: properties: speaker: type: string enum: - caller - assistant - omitted title: Speaker description: 'Who spoke. `omitted` is not speech: it marks where the middle of an unusually long call was left out, and its `text` says how many turns. The start and the end of the call are always kept.' text: type: string title: Text description: 'What was said, as transcribed automatically during the call. It can be wrong: background speech may be captured as the caller''s, and a turn may come out in the wrong language. Not a verbatim record.' offset_ms: anyOf: - type: integer - type: 'null' title: Offset Ms description: Milliseconds from the first turn of the call to the start of this one. Null when it was not measured, and on an `omitted` marker. duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms description: How long the turn lasted, in milliseconds. Null when not measured. interrupted: type: boolean title: Interrupted description: 'True when the caller spoke over the assistant and it stopped: the caller heard only the beginning of `text`. Always false for the caller.' unreliable: type: boolean title: Unreliable description: True when the transcription of this turn was judged to be noise. `text` is then a placeholder, not something anyone said. retranscribed: type: boolean title: Retranscribed description: True when this turn was transcribed again from the call audio after the call, and that transcription replaced the one made during the call. type: object required: - speaker - text - offset_ms - duration_ms - interrupted - unreliable - retranscribed title: TranscriptUtterance description: 'One turn of the conversation. Skip or mark a turn whose `unreliable` is true: its `text` is a placeholder. An `omitted` turn marks where the middle of a long call was left out.' TransferNumber: properties: label: type: string title: Label description: Who answers at this number, such as "Reception" or "Dr. Bianchi". The assistant uses it to pick the right target for a caller, and `call.transferred` reports it as `target_label`. phone: type: string title: Phone description: The number, E.164. type: object required: - label - phone title: TransferNumber description: A person or line the assistant may hand a call over to. TransferNumberInput: properties: label: type: string maxLength: 80 title: Label description: 'Who answers at this number, such as "Reception". Unique within the list, ignoring case: the assistant picks a target by its label.' phone: type: string title: Phone description: The number. E.164, or a national number, which is read in the country of the account's `phone_number`. Stored as E.164. A premium-rate or shared-cost number is refused, unless the list being replaced already holds it. type: object required: - label - phone title: TransferNumberInput description: A transfer target to store; the number is stored as E.164. UnresolvedRequest: properties: id: type: string title: Id description: Opaque Talki identifier for this request. location_id: type: string title: Location Id description: 'The location the question was about: that of the call it was raised on (`Call.location_id`). Never null, and it never changes.' call_id: anyOf: - type: string - type: 'null' title: Call Id description: The call it was raised on, readable through `GET /v1/calls/{id}` with `calls:read`. Null once that call has aged out of retention. caller_phone: anyOf: - type: string - type: 'null' title: Caller Phone description: E.164 number to call back, as presented. Null when the caller withheld it. question: type: string title: Question description: What the caller wanted to know, as the assistant recorded it. One line written by the assistant, not a transcript and never a quote. status: allOf: - $ref: '#/components/schemas/UnresolvedRequestStatus' description: '`open` — waiting on the business. `resolved` — dealt with. `dismissed` — closed without action. A request can return to `open`, which clears `resolved_at`.' answer: anyOf: - type: string - type: 'null' title: Answer description: 'What the business told the caller, noted when the request was resolved. Null when none was noted, and once the request is dismissed. It belongs to this request only: it does not teach the assistant anything.' created_at: type: string title: Created At description: RFC 3339 UTC. When the call raised it. format: date-time resolved_at: anyOf: - type: string format: date-time - type: 'null' title: Resolved At description: 'RFC 3339 UTC. Set when the status leaves `open`, for `dismissed` as well as `resolved`, and cleared if it returns to `open`. The object has no `updated_at`: its status and its answer are its only changes, and each sends `unresolved_request.updated`.' type: object required: - id - location_id - call_id - caller_phone - question - status - answer - created_at - resolved_at title: UnresolvedRequest description: A question the assistant could not answer on a call. It told the caller someone would get back to them; `status` says whether the business has. `question` is the assistant's one-line record of what was asked. UnresolvedRequestList: properties: data: items: $ref: '#/components/schemas/UnresolvedRequest' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 'Your position in the change feed after this page. Present on every page that returned data, including the last one. Store it and pass it back as `cursor` to receive only what has changed since. Null only when the page was empty. Opaque: do not parse it, and do not use it on another endpoint.' has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: UnresolvedRequestList description: A page of the unresolved-request change feed, oldest change first. UnresolvedRequestTeach: properties: question: type: string maxLength: 200 minLength: 1 title: Question description: 'The question, up to 200 characters, as callers ask it; usually the request''s `question`, reworded for everyone. Kept on one line: line breaks and repeated spaces become one space before the length is counted.' answer: type: string maxLength: 500 minLength: 1 title: Answer description: The answer, up to 500 characters, kept on one line like the question. location_id: anyOf: - type: string - type: 'null' title: Location Id description: 'Where the assistant uses it: a location id from `GET /v1/locations`, or `all` for every location, which adds the entry to the FAQ of each one. Omit it for the request''s own location. An account whose `multi_sede` is false has one FAQ, for every location: its main location''s id and `all` both go there. An id that is not one of the account''s locations is a 404.' type: object required: - question - answer title: UnresolvedRequestTeach description: The general answer to a resolved request's question, written as the business would say it to any caller. It is added to a FAQ note the business sees and edits in Talki. It is not the request's `answer`, which records what one caller was told, and does not change it. UnresolvedRequestTeaching: properties: unresolved_request_id: type: string title: Unresolved Request Id description: The request it was taught from. location_id: anyOf: - type: string - type: 'null' title: Location Id description: The location whose FAQ it went into; null for every location. taught_at: type: string title: Taught At description: When it was added, RFC 3339 UTC. format: date-time type: object required: - unresolved_request_id - location_id - taught_at title: UnresolvedRequestTeaching description: Where a taught answer went. The FAQ is indexed after the response, so the assistant uses the answer shortly after, not at once. UnresolvedRequestUpdate: properties: status: title: Status description: '`resolved` — dealt with. `dismissed` — closed without action, which clears `answer`. `open` — reopened, which clears `resolved_at` and keeps `answer`. Sending the status it already has changes nothing.' $ref: '#/components/schemas/UnresolvedRequestStatus' answer: anyOf: - type: string maxLength: 2000 - type: 'null' title: Answer description: What the business told the caller, up to 2000 characters, trimmed. Only a request that is `resolved`, or that this same request resolves, takes one. `null` or a blank text clears it. type: object title: UnresolvedRequestUpdate description: A new status for an unresolved request, the answer given to the caller, or both. Send at least one. Usage: properties: unlimited: type: boolean title: Unlimited description: 'True when nothing limits talk time: the plan sets no limit and the partner that manages the account has set no monthly minutes. The allowance fields are then null.' used_seconds: type: integer title: Used Seconds description: Talk time used in the current period. included_seconds: anyOf: - type: integer - type: 'null' title: Included Seconds description: 'Talk time included per period: the plan''s, or the monthly minutes the partner that manages the account set for it, when those are lower or the plan has no limit. Null when `unlimited`.' extra_seconds: type: integer title: Extra Seconds description: Bought extra talk time left right now. It is spent only once `included_seconds` is used up, and what is left carries over to the next period while the subscription is active. allowance_seconds: anyOf: - type: integer - type: 'null' title: Allowance Seconds description: 'Everything the current period may spend: `included_seconds` plus every bought second not spent in an earlier period. Null when `unlimited`.' remaining_seconds: anyOf: - type: integer - type: 'null' title: Remaining Seconds description: '`allowance_seconds` less `used_seconds`, never negative. Calls are refused when it reaches 0. Null when `unlimited`. To show it in minutes, round down, so no minute is shown that cannot be spent.' period_start: anyOf: - type: string format: date-time - type: 'null' title: Period Start description: When the current period began, RFC 3339 UTC. resets_at: anyOf: - type: string format: date-time - type: 'null' title: Resets At description: When `used_seconds` returns to 0 and the included time is available again, RFC 3339 UTC. Null when nothing will renew it, such as a subscription that has ended. type: object required: - unlimited - used_seconds - included_seconds - extra_seconds - allowance_seconds - remaining_seconds - period_start - resets_at title: Usage description: Talk time used in the current period and what is left, in seconds, for the whole account. To show minutes, round `remaining_seconds` down. For one location's share, read the current month of `GET /v1/usage/history` with its `location_id`, which can differ from this meter. UsageHistory: properties: months: items: $ref: '#/components/schemas/UsageMonth' type: array title: Months description: One entry per month asked for, oldest first. retained_since: type: string title: Retained Since description: Calls older than this, RFC 3339 UTC, have been deleted by Talki's retention, so a month before it reads less than was billed. format: date-time type: object required: - months - retained_since title: UsageHistory description: Talk time per calendar month, oldest first, from the call log. A call counts in the month it was answered in. A month is not a billing period, and the meter of `GET /v1/usage` adds a call once it has ended, so the current month can differ from it, and a call running past midnight into a new month counts here in the earlier one. A month reads less than was billed when some of its calls were deleted, through `DELETE /v1/calls/{call_id}` or in the apps, or are before `retained_since`. With `location_id`, only that location's calls count; the locations' months add up to the account's. UsageMonth: properties: month: type: string title: Month description: The month, `YYYY-MM`, in the account's `timezone`. start: type: string title: Start description: Local midnight on its 1st, RFC 3339 UTC. format: date-time end: type: string title: End description: Local midnight on the next month's 1st, RFC 3339 UTC, excluded. format: date-time used_seconds: type: integer title: Used Seconds description: 'Talk time billed for the calls answered in the month that are still in the call log: the sum of their `duration_seconds`. A deleted call is no longer counted, though its time stays billed. Zero for a month with no calls.' calls: type: integer title: Calls description: Calls answered in the month that billed time and are still in the call log. type: object required: - month - start - end - used_seconds - calls title: UsageMonth description: Talk time billed in one calendar month, in the account's `timezone`. Voice: properties: id: type: string title: Id description: Voice id, the value `voice` takes on the account. name: type: string title: Name description: Display name of the voice. gender: type: string enum: - female - male title: Gender description: Whether the voice sounds female or male. preview_url: type: string title: Preview Url description: Path of a short WAV sample of this voice, relative to the API base URL. Fetch it with the same credential. type: object required: - id - name - gender - preview_url title: Voice description: One voice the assistant can speak with on calls. Set it as `voice` with `PATCH /v1/account`. VoiceList: properties: data: items: $ref: '#/components/schemas/Voice' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page, or null on the last page. Pass it back unmodified as `cursor`; do not parse it. has_more: type: boolean title: Has More description: True when another page is available. default: false type: object required: - data - next_cursor - has_more title: VoiceList description: 'Every voice on offer, in one page: `next_cursor` is always null.' WorkingHours: properties: location_id: type: string title: Location Id description: 'The location these are the hours of, an id from `GET /v1/locations`: the one the request named with `location_id`, or the main location when it named none.' slots: items: $ref: '#/components/schemas/WorkingHoursSlot' type: array title: Slots description: Every weekly opening. A day with a lunch break has two slots. An empty list means the business has no regular opening hours, so the assistant offers callers no regular time to book. type: object required: - location_id - slots title: WorkingHours description: 'One location''s regular weekly opening hours, the main one unless `?location_id=` names another: what the assistant offers that location''s callers and what `GET /v1/availability` is computed from for its services. Dated exceptions are `Closure` objects. The response''s `ETag` goes back as `If-Match` on `PUT /v1/working_hours` with the same `location_id`.' WorkingHoursSlot: properties: days: items: type: integer maximum: 7.0 minimum: 1.0 type: array maxItems: 7 minItems: 1 title: Days description: 'Weekdays this range applies to, as ISO weekday numbers: 1 is Monday, 7 is Sunday.' start: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ title: Start description: Opening time, `HH:MM` in the account's `timezone`. end: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ title: End description: 'Closing time, `HH:MM` in the account''s `timezone`. Must be after `start`: a range cannot cross midnight, so split one that does into two slots on consecutive days.' type: object required: - days - start - end title: WorkingHoursSlot description: 'One weekly opening: a time range, in the account''s `timezone`, on one or more weekdays.' WorkingHoursUpdate: properties: slots: items: $ref: '#/components/schemas/WorkingHoursSlot' type: array maxItems: 20 title: Slots description: The whole week, replacing every existing slot. A slot left out is an opening removed. Send an empty list to remove all regular hours. type: object required: - slots title: WorkingHoursUpdate description: The whole week, replacing the current schedule. A slot you leave out is an opening removed, so read the hours first and send them back changed. DocumentCreate: additionalProperties: false description: A text note, sent as `application/json`. Its title and text are what the assistant reads. properties: source: default: text description: '`text`, or omit it. A website is sent with `website`.' enum: - text title: Source type: string title: description: Its title, at most 200 characters. The assistant reads it too. maxLength: 200 minLength: 1 title: Title type: string body: description: Its text, at most 100 KB in UTF-8. Plain text or Markdown. minLength: 1 title: Body type: string location_ids: anyOf: - items: type: string type: array - type: 'null' default: null description: Other locations that get a copy of it, ids from `GET /v1/locations`. Each copy is a document of its own, sharing `copy_group_id`. title: Location Ids required: - title - body title: DocumentCreate type: object DocumentSiteCreate: additionalProperties: false description: 'A website to import, sent as `application/json` with `source: "website"`: the page at `url`, or the `pages` listed, up to the plan''s page limit.' properties: source: description: '`website`.' enum: - website title: Source type: string url: description: The site's address, http or https. It becomes the document's `title`. maxLength: 2048 minLength: 1 title: Url type: string pages: anyOf: - items: type: string type: array - type: 'null' default: null description: The pages to read, from `POST /v1/documents/discover` or your own, at most the account plan's page limit. Omit to read the page at `url` alone. title: Pages location_ids: anyOf: - items: type: string type: array - type: 'null' default: null description: Other locations that get a copy of it, ids from `GET /v1/locations`. Each copy is a document of its own, sharing `copy_group_id`. title: Location Ids required: - source - url title: DocumentSiteCreate type: object DocumentUpload: description: 'A file, sent as `multipart/form-data`: PDF, DOCX, XLSX, TXT or CSV, at most 10 MB or the plan''s lower limit.' properties: file: description: 'The file: PDF, DOCX, XLSX, TXT or CSV, at most 10 MB or the account plan''s lower limit. Its name becomes the document''s `title`.' format: binary title: File type: string location_ids: anyOf: - items: type: string type: array - type: 'null' default: null description: Other locations that get a copy of it, ids from `GET /v1/locations`, one form field each. title: Location Ids required: - file title: DocumentUpload type: object DocumentReplace: additionalProperties: false description: A note's new text, sent as `application/json`. properties: body: description: Its new text, at most 100 KB in UTF-8. minLength: 1 title: Body type: string title: anyOf: - maxLength: 200 minLength: 1 type: string - type: 'null' default: null description: Its new title. Omit to keep the current one. title: Title required: - body title: DocumentReplace type: object DocumentSiteReplace: additionalProperties: false description: 'A website''s new import, sent as `application/json`: the `pages` listed, or else the pages it holds.' properties: pages: anyOf: - items: type: string type: array - type: 'null' default: null description: The pages to read this time. Omit to read again the pages it holds (`GET /v1/documents/{document_id}/pages`). title: Pages title: DocumentSiteReplace type: object DocumentFileReplace: description: A file's new version, sent as `multipart/form-data`. properties: file: description: The new file, under the same rules as an upload. Its name becomes the document's `title` once it is ready. format: binary title: File type: string required: - file title: DocumentFileReplace type: object ErrorDetail: type: object required: - type - code - message - request_id properties: type: type: string enum: - authentication_error - permission_error - invalid_request - conflict - rate_limit_error - api_error code: type: string description: 'Stable machine code; branch on this, not on `message`. Known codes: `invalid_credentials`, `insufficient_scope`, `account_closed`, `subscription_inactive`, `plan_upgrade_required`, `plan_feature_unavailable`, `forbidden`, `livemode_required`, `sandbox_api_key_required`, `unsupported_version`, `invalid_parameter`, `invalid_cursor`, `method_not_allowed`, `resource_not_found`, `conflict`, `precondition_failed`, `payload_too_large`, `export_too_large`, `idempotency_key_required`, `idempotency_key_reuse`, `request_in_progress`, `request_conflict`, `rate_limit_exceeded`, `ip_rate_limited`, `internal_error`, `api_error`, `booking_refused`, `appointment_cancelled`, `appointment_not_cancelled`, `unresolved_request_not_resolved`, `faq_full`, `document_not_ready`, `unsupported_file_type`, `service_has_upcoming_bookings`, `resource_is_default`, `resource_required_by_service`, `capacity_below_committed`, `capacity_below_service_requirement`, `resource_too_small`, `tag_limit_reached`, `caller_rule_limit_reached`, `transcript_not_available`, `trial_suspended`, `account_suspended`, `phone_number_missing`, `forwarding_number_missing`, `forwarding_number_invalid`, `check_in_progress`, `check_quota_exceeded`, `checks_busy`, `check_call_failed`, `agent_test_session_full`, `agent_test_unavailable`, `unknown_scenario`, `sandbox_not_ready`, `too_many_keys`, `key_not_active`, `key_already_rolled`, `invalid_registration`, `client_disabled`, `client_changed`, `delivery_in_progress`, `events_url_unset`, `events_paused`, `event_unsubscribed`, `account_refused`, `installation_inactive`, `invalid_client`, `invalid_request`, `unauthorized_client`, `access_denied`, `invalid_scope`, `slot_unavailable`, `capacity_exhausted`, `service_exclusion`, `closed_day`, `in_the_past`, `outside_hours`, `service_inactive`, `location_inactive`, `service_deleted`, `no_services_requested`, `party_too_large`, `stay_too_short`, `stay_too_long`, `stay_dates_invalid`. New codes may be added; treat an unknown one by its HTTP status.' message: type: string request_id: type: string description: The error itself. Branch on `code`; `message` is for people. ErrorEnvelope: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorDetail' description: Every error answer has this shape. AnswersAs: type: string enum: - business - owner description: 'Which name the assistant answers calls in and speaks for: `business` uses the business name, `owner` the account holder''s own name.' AppointmentStatus: type: string enum: - active - cancelled description: '`active` or `cancelled`. A cancelled appointment is kept, and can be restored to `active`.' CallerRuleKind: type: string enum: - vip - blocked description: '`vip` or `blocked`. A number is on one list at most at a location.' ClosureKind: type: string enum: - closed - open description: '`closed` for a closure, `open` for a special opening.' ExportFormat: type: string enum: - pdf - xlsx description: '`pdf` for a document, `xlsx` for an Excel sheet.' InboxStatus: type: string enum: - inbox - unread - archived - all description: '`inbox` — calls not archived. `unread` — calls not archived and not yet read. `archived` — archived calls. `all` — every call.' LineStatus: type: string enum: - no_number - unverified - verified description: Whether a line is proven to forward to Talki. `no_number` while there is no Talki number. `unverified` until a forwarding check of the current forwarding number has succeeded. `verified` once one has; it proves forwarding was on at `verified_at`, not that it still is. RangeUnit: type: string enum: - nights - days description: '`nights` (check-out day is free again) or `days` (the whole last day is held).' UnresolvedRequestStatus: type: string enum: - open - resolved - dismissed description: '`open` — waiting on the business. `resolved` — dealt with. `dismissed` — closed without action.' CallOutcome: type: string enum: - booked - rescheduled - cancelled - transferred - unresolved - info description: 'What a call came to: `booked` (it booked an appointment, not cancelled again on the same call), `rescheduled` (it moved one), `cancelled` (it cancelled one), `transferred` (a person took the call over), `unresolved` (it left a question for the owner), `info` (none of these). `Call.outcome` carries the same values, and may carry new ones.' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: A scoped account API key (`talki_live_…`, `talki_test_…`) or an OAuth access token (`talki_at_…`). servers: - url: https://api.talki.it description: Production tags: - name: Account description: Validate a credential, identify its Talki account, change the assistant's settings, set up call forwarding and finish onboarding. - name: Locations description: List the places the business works from, each with its own Talki number and line. - name: Agent test description: Chat in text with the account's assistant, as the test in the Talki apps does, to check how it answers before a caller does. - name: Usage description: Read the talk time used and left in the current period. - name: Voices description: List the voices the assistant can speak with, and fetch a sample of each. - name: Working hours description: Read and replace the weekly opening hours. - name: Closures description: List, add, change and remove the dated closures and special openings that override the weekly hours. - name: Calls description: Read the calls answered by Talki and their transcripts, file them, count and export them, and read the calls Talki refused. - name: Appointments description: Sync, create, reschedule and cancel bookings. - name: Contacts description: Sync, upsert and delete curated address-book contacts. - name: Pending contacts description: Approve or discard the names the assistant heard on calls. - name: Tags description: Label contacts. - name: Caller rules description: Manage the VIP and blocked numbers, and read the calls the block refused. - name: Services description: Sync the service catalogue, create a service with a fixed duration, update a service's name, description, price, duration or active state, and delete a service with no bookings still to come. - name: Resources description: Read the capacity a business books against, create a shared resource, rename a resource or change a shared resource's capacity, and delete a resource that is neither the default nor the only one a service draws on. - name: Unresolved requests description: Follow, resolve and dismiss the questions the assistant could not answer, and teach the assistant the answer for the next caller. - name: Documents description: 'Read and write the knowledge base the assistant answers callers from: text notes, uploaded files and imported websites, their indexing status, and whether the assistant uses each one.' - name: Availability description: Find bookable windows before creating an appointment. - name: Sandbox description: 'Drive a developer sandbox: tell it it had a call, and reset it to a known state. These endpoints answer 404 on a real Talki account.' webhooks: call.ringing: post: summary: call.ringing description: 'An inbound call reached the assistant, which is about to pick up. Not every ring is followed by a Call: a caller who hangs up before the pickup, or a call nobody says anything on, leaves none. Sent to the account''s webhooks, and to an OAuth app that subscribes to it while its installation grants `calls:read`.' parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - call.ringing created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: call_id: description: The id the Call will have once it ends, which ties this event to the `call.ended` that follows. `GET /v1/calls/{id}` answers 404 until then. title: Call Id type: string location_id: description: The location whose Talki number the caller dialled (`GET /v1/locations`). title: Location Id type: string caller: properties: contact_id: anyOf: - type: string - type: 'null' description: Talki contact this number resolves to, or null if the account has no contact for it. Stable per (account, number). title: Contact Id phone_number: anyOf: - type: string - type: 'null' description: Caller's number in E.164. Null when the CallerID was withheld. title: Phone Number display_name: anyOf: - type: string - type: 'null' description: Contact name, only when the account owner entered it by hand or imported it from their own address book. Null otherwise. title: Display Name vip: description: Whether the number is on the VIP list of the call's location (`/v1/caller_rules`). Never true without a number. title: Vip type: boolean required: - contact_id - phone_number - display_name - vip title: CallRingingCaller type: object description: Who is calling, as far as Talki may say. started_at: description: When the call arrived, RFC 3339 UTC. The Call's `started_at` is the same. title: Started At type: string format: date-time required: - call_id - location_id - caller - started_at type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: call.ringing 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: voice credential_id: null idempotency_key: null data: call_id: b7a41f0e-3c52-4d18-9e6a-2f8c1d7e5a34 location_id: 2c9e7b1a-6d40-4f35-8a12-9b3e5c7d1f60 caller: contact_id: 8e1d3f5a-2b64-4c97-a0d8-6f4b2e9c7a15 phone_number: '+393331112233' display_name: Mario Rossi vip: true started_at: '2026-09-22T15:02:11.482913Z' responses: 2XX: description: 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. call.ended: post: summary: call.ended description: A call ends and its summary is ready. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `calls:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - call.ended created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Call' description: The Call object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: call.ended 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: voice 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: 2XX: description: 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. call.transferred: post: summary: call.transferred description: The assistant transferred a call to a person. Sent when the call ends, once per transfer. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `calls:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - call.transferred created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: object: allOf: - $ref: '#/components/schemas/Call' description: The Call object, as the REST API returns it. target_label: description: The destination the assistant transferred to, by the name the owner gave it in Talki (e.g. `Reception`). Never the number behind it. Compare it case-insensitively. title: Target Label type: string transferred_at: anyOf: - type: string format: date-time - type: 'null' description: When the call was handed over, RFC 3339 UTC. title: Transferred At required: - object - target_label - transferred_at type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: call.transferred 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: voice 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: transferred transfers: - target_label: Reception at: '2026-09-22T15:03:30.512417Z' appointment_changes: [] unresolved_request_ids: [] created_at: '2026-09-15T09:18:03Z' read_at: '2026-09-15T10:02:11Z' archived_at: null target_label: Reception transferred_at: '2026-09-22T15:03:30.512417Z' responses: 2XX: description: 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. call.updated: post: summary: call.updated description: 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: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - call.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Call' description: The Call object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object 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: 2XX: description: 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. call.deleted: post: summary: call.deleted description: A call is deleted, in the Talki app or through the API. `data.object` is the call as it was; the call leaves the call log and the change feed. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `calls:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - call.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: object: allOf: - $ref: '#/components/schemas/Call' description: The Call object, as the REST API returns it. deleted: properties: unresolved_request_ids: description: 'The unresolved requests deleted with the call. They send no event of their own: delete them from your copy.' items: type: string title: Unresolved Request Ids type: array pending_contact_ids: description: The pending contacts deleted with the call. Each also sends `pending_contact.deleted` with `outcome` `discarded`. items: type: string title: Pending Contact Ids type: array required: - unresolved_request_ids - pending_contact_ids title: CallDeletedRelated type: object description: What was deleted with the call. required: - object - deleted type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: call.deleted 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 deleted: unresolved_request_ids: - 6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13 pending_contact_ids: [] responses: 2XX: description: 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. appointment.created: post: summary: appointment.created description: A new Talki appointment is committed. A booking made on a call arrives while the call is running, with `call_id` null. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `appointments:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - appointment.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Appointment' description: The Appointment object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: appointment.created 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: a3fe45ee-572f-4677-b1dd-f36c21bb47de location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: active client: contact_id: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d name: Giulia surname: Bianchi phone_number: '+393331234567' service: id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 name: Haircut start_at: '2026-10-08T09:00:00Z' end_at: '2026-10-08T09:30:00Z' quantity: 1 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 notes: First visit created_at: '2026-09-15T09:18:03Z' updated_at: '2026-09-15T09:18:03Z' responses: 2XX: description: 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. appointment.updated: post: summary: appointment.updated description: An appointment is edited, moved or restored; also, with `call_id` null, for each appointment booked by a call that is deleted. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `appointments:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - appointment.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Appointment' description: The Appointment object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: appointment.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: a3fe45ee-572f-4677-b1dd-f36c21bb47de location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: active client: contact_id: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d name: Giulia surname: Bianchi phone_number: '+393331234567' service: id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 name: Haircut start_at: '2026-10-08T09:00:00Z' end_at: '2026-10-08T09:30:00Z' quantity: 1 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 notes: First visit created_at: '2026-09-15T09:18:03Z' updated_at: '2026-09-15T09:18:03Z' responses: 2XX: description: 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. appointment.cancelled: post: summary: appointment.cancelled description: An appointment is cancelled. `data.object.status` is `cancelled`. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `appointments:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - appointment.cancelled created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Appointment' description: The Appointment object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: appointment.cancelled 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: a3fe45ee-572f-4677-b1dd-f36c21bb47de location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 status: cancelled client: contact_id: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d name: Giulia surname: Bianchi phone_number: '+393331234567' service: id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 name: Haircut start_at: '2026-10-08T09:00:00Z' end_at: '2026-10-08T09:30:00Z' quantity: 1 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 notes: First visit created_at: '2026-09-15T09:18:03Z' updated_at: '2026-09-15T09:18:03Z' responses: 2XX: description: 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. contact.created: post: summary: contact.created description: A curated contact is added. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - contact.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Contact' description: The Contact object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: contact.created 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: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d phone_number: '+393331234567' first_name: Giulia last_name: Bianchi display_name: Giulia Bianchi notes: Prefers morning appointments last_call_at: '2026-09-15T09:14:31Z' call_count: 3 created_at: '2026-08-20T12:00:00Z' updated_at: '2026-09-15T09:18:03Z' responses: 2XX: description: 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. contact.updated: post: summary: contact.updated description: A curated contact changes. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - contact.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Contact' description: The Contact object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: contact.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: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d phone_number: '+393331234567' first_name: Giulia last_name: Bianchi display_name: Giulia Bianchi notes: Prefers morning appointments last_call_at: '2026-09-15T09:14:31Z' call_count: 3 created_at: '2026-08-20T12:00:00Z' updated_at: '2026-09-15T09:18:03Z' responses: 2XX: description: 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. contact.deleted: post: summary: contact.deleted description: A curated contact is deleted, by a person, an app, or the data retention after twelve months without a call. `data.object` is the contact as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - contact.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Contact' description: The Contact object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: contact.deleted 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: 8fbb25f2-4f3b-4496-8aea-f0fc66de512d phone_number: '+393331234567' first_name: Giulia last_name: Bianchi display_name: Giulia Bianchi notes: Prefers morning appointments last_call_at: '2026-09-15T09:14:31Z' call_count: 3 created_at: '2026-08-20T12:00:00Z' updated_at: '2026-09-15T09:18:03Z' responses: 2XX: description: 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. pending_contact.created: post: summary: pending_contact.created description: The assistant hears a new caller's name, waiting for the owner. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - pending_contact.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/PendingContact' description: The PendingContact object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: pending_contact.created 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: d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68 phone_number: '+393334445555' first_name: Giulia last_name: null call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 created_at: '2026-10-06T15:02:44Z' responses: 2XX: description: 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. pending_contact.updated: post: summary: pending_contact.updated description: A later call refreshes a pending contact. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - pending_contact.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/PendingContact' description: The PendingContact object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: pending_contact.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: d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68 phone_number: '+393334445555' first_name: Giulia last_name: null call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 created_at: '2026-10-06T15:02:44Z' responses: 2XX: description: 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. pending_contact.deleted: post: summary: pending_contact.deleted description: A pending contact is approved or discarded. `data.object` is the pending contact as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - pending_contact.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: object: allOf: - $ref: '#/components/schemas/PendingContact' description: The PendingContact object, as the REST API returns it. outcome: description: '`approved`: it became a contact, which sends its own `contact.*` event. `discarded`: the owner or an app discarded it, the data retention removed it, or the call that proposed it was deleted.' enum: - approved - discarded title: Outcome type: string required: - object - outcome type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: pending_contact.deleted 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: d58a2f17-6c4b-4e93-a1f0-7b3c9e2d5a68 phone_number: '+393334445555' first_name: Giulia last_name: null call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 created_at: '2026-10-06T15:02:44Z' outcome: approved responses: 2XX: description: 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. tag.created: post: summary: tag.created description: A tag is created. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - tag.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Tag' description: The Tag object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: tag.created 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: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Suppliers color: '#e0867a' contact_ids: - 8fbb25f2-4f3b-4496-8aea-f0fc66de512d created_at: '2026-10-01T08:00:00Z' responses: 2XX: description: 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. tag.updated: post: summary: tag.updated description: A tag is renamed, put on or taken off a contact, or a contact carrying it is deleted. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - tag.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Tag' description: The Tag object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: tag.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: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Suppliers color: '#e0867a' contact_ids: - 8fbb25f2-4f3b-4496-8aea-f0fc66de512d created_at: '2026-10-01T08:00:00Z' responses: 2XX: description: 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. tag.deleted: post: summary: tag.deleted description: A tag is deleted. `data.object` is the tag as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - tag.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Tag' description: The Tag object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: tag.deleted 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: 4b9e1c62-7a3d-4f08-b5c1-93e2d7a6f014 name: Suppliers color: '#e0867a' contact_ids: - 8fbb25f2-4f3b-4496-8aea-f0fc66de512d created_at: '2026-10-01T08:00:00Z' responses: 2XX: description: 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. caller_rule.created: post: summary: caller_rule.created description: A VIP or blocked number is added. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - caller_rule.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/CallerRule' description: The CallerRule object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: caller_rule.created 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: 93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30 phone_number: '+393401234567' location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 kind: blocked label: Telemarketing created_at: '2026-10-02T09:10:00Z' updated_at: '2026-10-02T09:10:00Z' responses: 2XX: description: 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. caller_rule.updated: post: summary: caller_rule.updated description: A VIP or blocked number is changed, or moved between the two lists. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - caller_rule.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/CallerRule' description: The CallerRule object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: caller_rule.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: 93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30 phone_number: '+393401234567' location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 kind: blocked label: Telemarketing created_at: '2026-10-02T09:10:00Z' updated_at: '2026-10-02T09:10:00Z' responses: 2XX: description: 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. caller_rule.deleted: post: summary: caller_rule.deleted description: A VIP or blocked number is removed. `data.object` is the rule as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `contacts:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - caller_rule.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/CallerRule' description: The CallerRule object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: caller_rule.deleted 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: 93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30 phone_number: '+393401234567' location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 kind: blocked label: Telemarketing created_at: '2026-10-02T09:10:00Z' updated_at: '2026-10-02T09:10:00Z' responses: 2XX: description: 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. account.updated: post: summary: account.updated description: A writable field of the account, `onboarding_completed` or `phone_number` changes at the main location, or `call_auto_archive_days` changes. `data.object` is the account at the main location. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - account.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Account' description: The Account object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: account.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: f7e39b9a-1ac8-45e4-93da-2600f17cb286 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 business_name: Studio Bellini timezone: Europe/Rome livemode: true test: false business_information: Free parking in the courtyard behind the salon. We do not sell gift cards. instructions: null voice: Sulafat answers_as: business call_auto_archive_days: null greeting: null call_opening: null multilingual_enabled: true languages: primary: it supported: - it - en - fr - de - es service_area: Bergamo e provincia transfer_numbers: [] bookings_enabled: true unresolved_requests_enabled: true remember_callers: true store_transcripts: true notify_on_every_call: true notify_on_incoming_call: false phone_number: '+390350000001' forwarding_number: '+393331112222' line: phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' multi_sede: true onboarding_completed: true responses: 2XX: description: 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. working_hours.updated: post: summary: working_hours.updated description: The main location's weekly opening hours change. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - working_hours.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/WorkingHours' description: The WorkingHours object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: working_hours.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: location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 slots: - days: - 2 - 3 - 4 - 5 start: 09:00 end: '13:00' - days: - 2 - 3 - 4 - 5 start: '14:30' end: '19:00' - days: - 6 start: 09:00 end: '17:00' responses: 2XX: description: 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. closure.created: post: summary: closure.created description: A closure or special opening is added. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - closure.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Closure' description: The Closure object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: closure.created 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: e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35 location_id: null kind: closed all_day: true start_date: '2026-12-24' end_date: '2026-12-26' start_at: '2026-12-23T23:00:00Z' end_at: '2026-12-26T23:00:00Z' reason: Christmas holidays created_at: '2026-09-30T08:12:44Z' responses: 2XX: description: 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. closure.updated: post: summary: closure.updated description: A closure or special opening is changed. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - closure.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Closure' description: The Closure object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: closure.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: e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35 location_id: null kind: closed all_day: true start_date: '2026-12-24' end_date: '2026-12-26' start_at: '2026-12-23T23:00:00Z' end_at: '2026-12-26T23:00:00Z' reason: Christmas holidays created_at: '2026-09-30T08:12:44Z' responses: 2XX: description: 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. closure.deleted: post: summary: closure.deleted description: A closure or special opening is removed. `data.object` is the closure as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - closure.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Closure' description: The Closure object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: closure.deleted 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: e2a7c9d4-5b18-4f63-8a0e-9c4d2b7f1e35 location_id: null kind: closed all_day: true start_date: '2026-12-24' end_date: '2026-12-26' start_at: '2026-12-23T23:00:00Z' end_at: '2026-12-26T23:00:00Z' reason: Christmas holidays created_at: '2026-09-30T08:12:44Z' responses: 2XX: description: 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. location.created: post: summary: location.created description: A location is added. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - location.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Location' description: The Location object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: location.created 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: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Studio Bellini is_default: true status: active phone_number: '+390350000001' line: phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' position: 0 created_at: '2026-08-01T08:00:00Z' deactivated_at: null responses: 2XX: description: 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. location.updated: post: summary: location.updated description: A location's name, order, Talki number or line changes. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - location.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Location' description: The Location object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: location.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: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Studio Bellini is_default: true status: active phone_number: '+390350000001' line: phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' position: 0 created_at: '2026-08-01T08:00:00Z' deactivated_at: null responses: 2XX: description: 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. location.deactivated: post: summary: location.deactivated description: A location is switched off, by the owner or by the plan. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - location.deactivated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Location' description: The Location object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: location.deactivated 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: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Studio Bellini is_default: true status: active phone_number: '+390350000001' line: phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' position: 0 created_at: '2026-08-01T08:00:00Z' deactivated_at: null responses: 2XX: description: 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. location.reactivated: post: summary: location.reactivated description: A location is switched back on, by the owner or by the plan. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - location.reactivated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Location' description: The Location object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: location.reactivated 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: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Studio Bellini is_default: true status: active phone_number: '+390350000001' line: phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' position: 0 created_at: '2026-08-01T08:00:00Z' deactivated_at: null responses: 2XX: description: 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. location.settings_updated: post: summary: location.settings_updated description: A location other than the main one changes the assistant settings it keeps for itself. `data.object` is the account at that location. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - location.settings_updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Account' description: The Account object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: location.settings_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: f7e39b9a-1ac8-45e4-93da-2600f17cb286 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 business_name: Studio Bellini timezone: Europe/Rome livemode: true test: false business_information: Free parking in the courtyard behind the salon. We do not sell gift cards. instructions: null voice: Sulafat answers_as: business call_auto_archive_days: null greeting: null call_opening: null multilingual_enabled: true languages: primary: it supported: - it - en - fr - de - es service_area: Bergamo e provincia transfer_numbers: [] bookings_enabled: true unresolved_requests_enabled: true remember_callers: true store_transcripts: true notify_on_every_call: true notify_on_incoming_call: false phone_number: '+390350000001' forwarding_number: '+393331112222' line: phone_number: '+390350000001' forwarding_number: '+393331112222' status: verified verified_at: '2026-10-07T09:30:12Z' multi_sede: true onboarding_completed: true responses: 2XX: description: 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. location.working_hours_updated: post: summary: location.working_hours_updated description: The weekly hours of a location other than the main one change. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `account:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - location.working_hours_updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/WorkingHours' description: The WorkingHours object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: location.working_hours_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: location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 slots: - days: - 2 - 3 - 4 - 5 start: 09:00 end: '13:00' - days: - 2 - 3 - 4 - 5 start: '14:30' end: '19:00' - days: - 6 start: 09:00 end: '17:00' responses: 2XX: description: 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. service.created: post: summary: service.created description: A service is added. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `services:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - service.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Service' description: The Service object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: service.created 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: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Haircut description: Wash and cut price: 30€ duration_minutes: 30 booking_mode: duration range_unit: null min_stay: null max_stay: null checkin_time: null checkout_time: null asks_quantity: false quantity_label: null min_quantity: 1 max_quantity: null is_active: true created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' responses: 2XX: description: 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. service.updated: post: summary: service.updated description: A service is changed, switched off or on. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `services:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - service.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Service' description: The Service object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: service.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: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Haircut description: Wash and cut price: 30€ duration_minutes: 30 booking_mode: duration range_unit: null min_stay: null max_stay: null checkin_time: null checkout_time: null asks_quantity: false quantity_label: null min_quantity: 1 max_quantity: null is_active: true created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' responses: 2XX: description: 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. service.deleted: post: summary: service.deleted description: A service is deleted. `data.object` is the service as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `services:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - service.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Service' description: The Service object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: service.deleted 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: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Haircut description: Wash and cut price: 30€ duration_minutes: 30 booking_mode: duration range_unit: null min_stay: null max_stay: null checkin_time: null checkout_time: null asks_quantity: false quantity_label: null min_quantity: 1 max_quantity: null is_active: true created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' responses: 2XX: description: 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. resource.created: post: summary: resource.created description: A resource is added. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `resources:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - resource.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Resource' description: The Resource object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: resource.created 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: b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Dining room mode: units capacity: 4 max_party_size: 8 combine_across_classes: false unit_classes: - id: 1f2b9c07-3d64-4a1e-8f95-2b7c6d0e4a31 name: Four-tops size: 4 count: 6 combinable: true combine_max: 2 services: - service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 rate: 1 owner_service_id: null is_default: false created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' responses: 2XX: description: 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. resource.updated: post: summary: resource.updated description: A resource is changed, or gains or loses a service. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `resources:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - resource.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Resource' description: The Resource object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: resource.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: b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Dining room mode: units capacity: 4 max_party_size: 8 combine_across_classes: false unit_classes: - id: 1f2b9c07-3d64-4a1e-8f95-2b7c6d0e4a31 name: Four-tops size: 4 count: 6 combinable: true combine_max: 2 services: - service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 rate: 1 owner_service_id: null is_default: false created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' responses: 2XX: description: 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. resource.deleted: post: summary: resource.deleted description: A resource is deleted. `data.object` is the resource as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `resources:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - resource.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Resource' description: The Resource object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: resource.deleted 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: b91c5d3e-0c1a-4a2f-9e6b-7c0d4e8f1a52 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 name: Dining room mode: units capacity: 4 max_party_size: 8 combine_across_classes: false unit_classes: - id: 1f2b9c07-3d64-4a1e-8f95-2b7c6d0e4a31 name: Four-tops size: 4 count: 6 combinable: true combine_max: 2 services: - service_id: 45c470b7-592a-42cd-8ce8-5d7a0a497d26 rate: 1 owner_service_id: null is_default: false created_at: '2026-08-01T08:00:00Z' updated_at: '2026-09-10T10:30:00Z' responses: 2XX: description: 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. document.created: post: summary: document.created description: A document is added to the knowledge base, with `status` `processing`. One event per document, each copy at another location included. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `knowledge:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - document.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Document' description: The Document object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: document.created 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: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 1 status: ready status_error: null enabled: true faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-28T09:12:40Z' responses: 2XX: description: 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. document.updated: post: summary: document.updated description: A document's title, content or `enabled` changes, it turns `processing` again, or its indexing ends `ready` or `failed`. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `knowledge:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - document.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Document' description: The Document object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: document.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: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 1 status: ready status_error: null enabled: true faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-28T09:12:40Z' responses: 2XX: description: 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. document.deleted: post: summary: document.deleted description: A document is deleted. `data.object` is the document as it was. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `knowledge:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - document.deleted created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/Document' description: The Document object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: document.deleted 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: 5d2e8b17-3c9a-4f60-b4e1-8a7c2d9f0e36 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 title: Is there parking? source: text mime_type: text/markdown size_bytes: 59 chunk_count: 1 status: ready status_error: null enabled: true faq: false file_available: false copy_group_id: c41f7a29-6e3b-4d85-9f02-1b8e5c7a3d94 created_at: '2026-10-28T09:12:40Z' updated_at: '2026-10-28T09:12:40Z' responses: 2XX: description: 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. unresolved_request.updated: post: summary: unresolved_request.updated description: An unresolved request is resolved, dismissed or reopened, or its `answer` changes. Sent to the account's webhooks, and to an OAuth app that subscribes to it while its installation grants `unresolved:read`. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - unresolved_request.updated created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: type: object properties: object: allOf: - $ref: '#/components/schemas/UnresolvedRequest' description: The UnresolvedRequest object, as the REST API returns it. required: - object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: unresolved_request.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: 6c1f9a74-1d0b-4c8e-9a3d-2f5b7e0c4d13 location_id: 0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40 call_id: 38d23d84-02d2-4418-b169-3608aa04a8f8 caller_phone: '+393331234567' question: Whether the salon does bridal hair on Sundays. status: open answer: null created_at: '2026-09-15T09:18:03Z' resolved_at: null responses: 2XX: description: 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. usage.threshold_reached: post: summary: usage.threshold_reached description: 'A call ends leaving 25% or less of the period''s allowance: the plan''s included minutes plus any extra minutes. Sent once per crossing, and not on a plan with no minute cap. When the same call also sends `usage.extra_credits_low`, this event is not sent for that crossing. Sent to the account''s webhooks and to the app of the partner that pays for the account; no other app receives it.' parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - usage.threshold_reached created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: used_seconds: description: 'Seconds used in the current billing period, this call included: plan and extra minutes together.' title: Used Seconds type: integer included_seconds: description: 'Seconds included in the period, without extra minutes: the same figure as `Usage.included_seconds`.' title: Included Seconds type: integer allowance_seconds: description: 'Everything the account may spend in the period: `included_seconds` plus the extra seconds it held when the period began and any added since. Equal to `included_seconds` when it has none.' title: Allowance Seconds type: integer remaining_seconds: description: '`allowance_seconds` minus `used_seconds`, never below 0.' title: Remaining Seconds type: integer percent_used: description: '`used_seconds` as a percentage of `allowance_seconds`, to one decimal place. Above 100 when a call ran past the allowance.' title: Percent Used type: number extra_seconds: description: Extra seconds still unspent after this call; 0 when the account has none. title: Extra Seconds type: integer minutes_used: description: '`used_seconds` rounded to the nearest whole minute. For display.' title: Minutes Used type: integer minutes_included: description: 'Minutes included in the period, without extra minutes: `Usage.included_seconds` in minutes.' title: Minutes Included type: integer minutes_remaining: description: '`remaining_seconds` in whole minutes, rounded down. For display.' title: Minutes Remaining type: integer seconds_used: deprecated: true description: The same value as `used_seconds`. title: Seconds Used type: integer seconds_included: deprecated: true description: The same value as `included_seconds`. title: Seconds Included type: integer seconds_allowance: deprecated: true description: The same value as `allowance_seconds`. title: Seconds Allowance type: integer seconds_remaining: deprecated: true description: The same value as `remaining_seconds`. title: Seconds Remaining type: integer extra_seconds_balance: deprecated: true description: The same value as `extra_seconds`. title: Extra Seconds Balance type: integer required: - used_seconds - included_seconds - allowance_seconds - remaining_seconds - percent_used - extra_seconds - minutes_used - minutes_included - minutes_remaining - seconds_used - seconds_included - seconds_allowance - seconds_remaining - extra_seconds_balance type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: usage.threshold_reached 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: voice credential_id: null idempotency_key: null data: minutes_used: 271 minutes_included: 300 minutes_remaining: 89 seconds_used: 16245 seconds_included: 18000 seconds_remaining: 5355 extra_seconds_balance: 3600 seconds_allowance: 21600 percent_used: 75.2 used_seconds: 16245 included_seconds: 18000 allowance_seconds: 21600 remaining_seconds: 5355 extra_seconds: 3600 responses: 2XX: description: 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. usage.extra_credits_low: post: summary: usage.extra_credits_low description: A call ends with the extra-minutes balance below the floor the account owner set (10 minutes unless changed). Not sent again until the balance is back over the floor or the owner changes the floor; never sent with a floor of 0, with no extra minutes, or on a plan with no minute cap. Sent to the account's webhooks and to the app of the partner that pays for the account; no other app receives it. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - usage.extra_credits_low created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: extra_seconds: description: Extra seconds still unspent after this call. Can be 0. title: Extra Seconds type: integer extra_minutes_balance: description: '`extra_seconds` in whole minutes, rounded down. Can be 0.' title: Extra Minutes Balance type: integer threshold_minutes: description: The account owner's floor, in minutes, that the balance is now below. title: Threshold Minutes type: integer used_seconds: description: 'Seconds used in the current billing period, this call included: plan and extra minutes together.' title: Used Seconds type: integer minutes_included: description: 'Minutes included in the period, without extra minutes: `Usage.included_seconds` in minutes.' title: Minutes Included type: integer extra_seconds_balance: deprecated: true description: The same value as `extra_seconds`. title: Extra Seconds Balance type: integer seconds_used: deprecated: true description: The same value as `used_seconds`. title: Seconds Used type: integer required: - extra_seconds - extra_minutes_balance - threshold_minutes - used_seconds - minutes_included - extra_seconds_balance - seconds_used type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: usage.extra_credits_low 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: voice credential_id: null idempotency_key: null data: extra_seconds_balance: 505 extra_minutes_balance: 8 threshold_minutes: 10 seconds_used: 21095 minutes_included: 300 used_seconds: 21095 extra_seconds: 505 responses: 2XX: description: 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. ping: post: summary: ping description: The account owner chooses **Invia test** on a webhook endpoint. Sent only to that endpoint, whatever it subscribes to; never to an app. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - ping created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: anyOf: - properties: source: description: '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.' title: Source type: string x-extensible-enum: - voice - dashboard - api - system credential_id: anyOf: - type: string - type: 'null' description: 'With `source` `api`, the credential that made the change: an API key''s ID, or an OAuth app''s installation ID. On an app event it is set only when your own installation made the change, and null when another app or one of the account''s API keys did. Null for every other `source`.' title: Credential Id idempotency_key: anyOf: - type: string - type: 'null' description: The `Idempotency-Key` of the request that made the change, whenever `credential_id` is set and the request sent one. Null otherwise. title: Idempotency Key required: - source - credential_id - idempotency_key title: EventOrigin type: object - type: 'null' description: What caused the change. Null on installation events, and null when the cause was not recorded; treat null as unknown. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: message: description: Always `Test event from Talki`. title: Message type: string required: - message type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: ping 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: message: Test event from Talki responses: 2XX: description: 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. installation.created: post: summary: installation.created description: An account installs your app, or reinstalls it after a disconnect. Sent to your app's events URL, with no subscription. Sent to your OAuth app's events URL only. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - installation.created created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: type: 'null' description: Always null on installation events. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: installation: properties: object: description: Always `installation`. title: Object type: string id: description: 'The installation''s ID: one account''s connection to your app. The same value as `installation_id` on the envelope.' title: Id type: string client_id: description: Your app's client ID. title: Client Id type: string account_id: description: The Talki account that installed the app. title: Account Id type: string scopes: description: The scopes the account granted, sorted. items: type: string title: Scopes type: array status: description: '`active`, or `revoked` once the installation is disconnected.' enum: - active - revoked title: Status type: string access: description: '`suspended` while the account cannot use the API, otherwise `active`. The grant and its tokens survive a suspension.' enum: - active - suspended title: Access type: string livemode: description: '`false` for a sandbox account''s installation.' title: Livemode type: boolean created_at: anyOf: - type: string format: date-time - type: 'null' description: When the account first installed the app, ISO 8601 with a `+00:00` offset, possibly with microseconds. title: Created At revoked_at: anyOf: - type: string format: date-time - type: 'null' description: When the installation was disconnected, in the same format; null while it is active. title: Revoked At required: - object - id - client_id - account_id - scopes - status - access - livemode - created_at - revoked_at title: Installation type: object description: The installation, as it is after the change. required: - installation type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data - installation_id type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: installation.created 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: null installation_id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 data: installation: object: installation id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 client_id: talki_cid_4Hq2mZ8rVt1LxN3pYw7KcA account_id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 scopes: - appointments:read - calls:read status: active access: active livemode: true created_at: '2026-09-15T09:14:31.204518+00:00' revoked_at: null responses: 2XX: description: 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. installation.scopes_changed: post: summary: installation.scopes_changed description: An account reconnects your app with a different set of scopes. A reconnect with the same scopes sends nothing. Sent to your OAuth app's events URL only. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - installation.scopes_changed created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: type: 'null' description: Always null on installation events. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: installation: properties: object: description: Always `installation`. title: Object type: string id: description: 'The installation''s ID: one account''s connection to your app. The same value as `installation_id` on the envelope.' title: Id type: string client_id: description: Your app's client ID. title: Client Id type: string account_id: description: The Talki account that installed the app. title: Account Id type: string scopes: description: The scopes the account granted, sorted. items: type: string title: Scopes type: array status: description: '`active`, or `revoked` once the installation is disconnected.' enum: - active - revoked title: Status type: string access: description: '`suspended` while the account cannot use the API, otherwise `active`. The grant and its tokens survive a suspension.' enum: - active - suspended title: Access type: string livemode: description: '`false` for a sandbox account''s installation.' title: Livemode type: boolean created_at: anyOf: - type: string format: date-time - type: 'null' description: When the account first installed the app, ISO 8601 with a `+00:00` offset, possibly with microseconds. title: Created At revoked_at: anyOf: - type: string format: date-time - type: 'null' description: When the installation was disconnected, in the same format; null while it is active. title: Revoked At required: - object - id - client_id - account_id - scopes - status - access - livemode - created_at - revoked_at title: Installation type: object description: The installation, as it is after the change. previous_scopes: description: The scopes granted before the reconnect, sorted. The new ones are in `installation.scopes`. items: type: string title: Previous Scopes type: array required: - installation - previous_scopes type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data - installation_id type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: installation.scopes_changed 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: null installation_id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 data: installation: object: installation id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 client_id: talki_cid_4Hq2mZ8rVt1LxN3pYw7KcA account_id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 scopes: - appointments:read - calls:read status: active access: active livemode: true created_at: '2026-09-15T09:14:31.204518+00:00' revoked_at: null previous_scopes: - calls:read responses: 2XX: description: 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. installation.revoked: post: summary: installation.revoked description: The installation is disconnected. Sent to your OAuth app's events URL only. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - installation.revoked created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: type: 'null' description: Always null on installation events. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: installation: properties: object: description: Always `installation`. title: Object type: string id: description: 'The installation''s ID: one account''s connection to your app. The same value as `installation_id` on the envelope.' title: Id type: string client_id: description: Your app's client ID. title: Client Id type: string account_id: description: The Talki account that installed the app. title: Account Id type: string scopes: description: The scopes the account granted, sorted. items: type: string title: Scopes type: array status: description: '`active`, or `revoked` once the installation is disconnected.' enum: - active - revoked title: Status type: string access: description: '`suspended` while the account cannot use the API, otherwise `active`. The grant and its tokens survive a suspension.' enum: - active - suspended title: Access type: string livemode: description: '`false` for a sandbox account''s installation.' title: Livemode type: boolean created_at: anyOf: - type: string format: date-time - type: 'null' description: When the account first installed the app, ISO 8601 with a `+00:00` offset, possibly with microseconds. title: Created At revoked_at: anyOf: - type: string format: date-time - type: 'null' description: When the installation was disconnected, in the same format; null while it is active. title: Revoked At required: - object - id - client_id - account_id - scopes - status - access - livemode - created_at - revoked_at title: Installation type: object description: The installation, as it is after the change. reason: description: 'Who disconnected: `customer` (the account owner, in the Talki app), `partner` (your app, through `/oauth/revoke`) or `account_deleted` (the account was closed).' enum: - customer - partner - account_deleted title: Reason type: string required: - installation - reason type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data - installation_id type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: installation.revoked 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: null installation_id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 data: installation: object: installation id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 client_id: talki_cid_4Hq2mZ8rVt1LxN3pYw7KcA account_id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 scopes: - appointments:read - calls:read status: revoked access: active livemode: true created_at: '2026-09-15T09:14:31.204518+00:00' revoked_at: '2026-09-20T16:02:11.482913+00:00' reason: customer responses: 2XX: description: 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. installation.access_suspended: post: summary: installation.access_suspended description: The account can no longer use the API. Can arrive up to 15 minutes after the change. Sent to your OAuth app's events URL only. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - installation.access_suspended created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: type: 'null' description: Always null on installation events. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: installation: properties: object: description: Always `installation`. title: Object type: string id: description: 'The installation''s ID: one account''s connection to your app. The same value as `installation_id` on the envelope.' title: Id type: string client_id: description: Your app's client ID. title: Client Id type: string account_id: description: The Talki account that installed the app. title: Account Id type: string scopes: description: The scopes the account granted, sorted. items: type: string title: Scopes type: array status: description: '`active`, or `revoked` once the installation is disconnected.' enum: - active - revoked title: Status type: string access: description: '`suspended` while the account cannot use the API, otherwise `active`. The grant and its tokens survive a suspension.' enum: - active - suspended title: Access type: string livemode: description: '`false` for a sandbox account''s installation.' title: Livemode type: boolean created_at: anyOf: - type: string format: date-time - type: 'null' description: When the account first installed the app, ISO 8601 with a `+00:00` offset, possibly with microseconds. title: Created At revoked_at: anyOf: - type: string format: date-time - type: 'null' description: When the installation was disconnected, in the same format; null while it is active. title: Revoked At required: - object - id - client_id - account_id - scopes - status - access - livemode - created_at - revoked_at title: Installation type: object description: The installation, as it is after the change. reason: description: The error code the account's API calls now receive. Stop syncing until `installation.access_restored`. enum: - subscription_inactive - plan_upgrade_required - account_closed title: Reason type: string required: - installation - reason type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data - installation_id type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: installation.access_suspended 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: null installation_id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 data: installation: object: installation id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 client_id: talki_cid_4Hq2mZ8rVt1LxN3pYw7KcA account_id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 scopes: - appointments:read - calls:read status: active access: suspended livemode: true created_at: '2026-09-15T09:14:31.204518+00:00' revoked_at: null reason: subscription_inactive responses: 2XX: description: 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. installation.access_restored: post: summary: installation.access_restored description: The account can use the API again. Can arrive up to 15 minutes after the change. Sent to your OAuth app's events URL only. parameters: - name: X-Talki-Signature in: header required: true description: '`t=,v1=`, the HMAC computed over `.` with the signing secret. During a secret rotation it carries one `v1` per secret: accept the request if any matches.' schema: type: string - name: X-Talki-Event in: header required: true description: The event type, as in `type`. schema: type: string - name: X-Talki-Delivery in: header required: true description: The event ID, as in `id`. schema: type: string requestBody: required: true content: application/json: schema: properties: id: description: 'The event''s ID, `evt_` and 32 hex characters. Equal to the `X-Talki-Delivery` header and unchanged on a redelivery: deduplicate on it.' title: Id type: string type: type: string enum: - installation.access_restored created_at: description: When the event was written, ISO 8601 with a `+00:00` offset, possibly with microseconds. Parse it as an instant. title: Created At type: string format: date-time api_version: description: 'The dated contract version `data` is shaped for: the endpoint''s version on a webhook, the app''s on an app event.' title: Api Version type: string account_id: description: The Talki account the event happened on. title: Account Id type: string livemode: description: '`false` for an event from a sandbox account.' title: Livemode type: boolean origin: type: 'null' description: Always null on installation events. installation_id: anyOf: - type: string - type: 'null' default: null description: 'On app events only: the installation the event belongs to. Absent from an account''s own webhooks.' title: Installation Id data: properties: installation: properties: object: description: Always `installation`. title: Object type: string id: description: 'The installation''s ID: one account''s connection to your app. The same value as `installation_id` on the envelope.' title: Id type: string client_id: description: Your app's client ID. title: Client Id type: string account_id: description: The Talki account that installed the app. title: Account Id type: string scopes: description: The scopes the account granted, sorted. items: type: string title: Scopes type: array status: description: '`active`, or `revoked` once the installation is disconnected.' enum: - active - revoked title: Status type: string access: description: '`suspended` while the account cannot use the API, otherwise `active`. The grant and its tokens survive a suspension.' enum: - active - suspended title: Access type: string livemode: description: '`false` for a sandbox account''s installation.' title: Livemode type: boolean created_at: anyOf: - type: string format: date-time - type: 'null' description: When the account first installed the app, ISO 8601 with a `+00:00` offset, possibly with microseconds. title: Created At revoked_at: anyOf: - type: string format: date-time - type: 'null' description: When the installation was disconnected, in the same format; null while it is active. title: Revoked At required: - object - id - client_id - account_id - scopes - status - access - livemode - created_at - revoked_at title: Installation type: object description: The installation, as it is after the change. required: - installation type: object description: The event's payload. required: - id - type - created_at - api_version - account_id - livemode - origin - data - installation_id type: object example: id: evt_04d8e87897db4ecab459a456ea55e754 type: installation.access_restored 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: null installation_id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 data: installation: object: installation id: 5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90 client_id: talki_cid_4Hq2mZ8rVt1LxN3pYw7KcA account_id: f7e39b9a-1ac8-45e4-93da-2600f17cb286 scopes: - appointments:read - calls:read status: active access: active livemode: true created_at: '2026-09-15T09:14:31.204518+00:00' revoked_at: null responses: 2XX: description: 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.