Quickstart

Six steps: a Talki account of your own, a call it took, that call read back, and the signed webhook it produced.

You do not need a Talki customer for any of it. Registering an app gets you a sandbox: a real Talki account with a real business in it, a salon in Verona with services, opening hours, four weeks of calls and a contact book, that you own and can reset.

1. Register an app and take your sandbox key

Register your app in the console. The sandbox is issued at that moment, not when the app is approved; approval decides only whether real businesses may install you.

The console shows the sandbox’s account ID and mints a key for it. The secret is shown once; a lost key is replaced, never recovered.

talki_live_…   production
talki_test_…   test mode — every sandbox key is one of these

Keep it in a server-side secret store:

export TALKI_API_KEY='talki_test_…'

The sandbox has no phone number

It cannot receive a real call. You trigger one instead — step 5.

2. Validate the credential

curl --fail-with-body https://api.talki.it/v1/account \
  -H "Authorization: Bearer $TALKI_API_KEY" \
  -H "Accept: application/json"

{
  "id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
  "business_name": "Salone Bellini",
  "timezone": "Europe/Rome",
  "livemode": false,
  "business_information": null,
  "instructions": null,
  "voice": "Sulafat"
}

Needs account:read. livemode is false because the credential does not act on real data: it is a test-mode key, or an app installed on a sandbox. Every webhook carries the same flag, so one receiver can serve test and production traffic and still tell them apart.

Use an SDK

The steps below use curl. The same call with the Python SDK is talki.account.get(), and with the TypeScript SDK await talki.account.get(); both read TALKI_API_KEY from the environment.

3. Read the latest calls

curl --fail-with-body 'https://api.talki.it/v1/calls?limit=10' \
  -H "Authorization: Bearer $TALKI_API_KEY"

Newest first. Follow next_cursor while has_more is true; on the last page it is null.

4. Establish a recovery cursor

A durable integration also walks the call change feed:

curl --fail-with-body 'https://api.talki.it/v1/calls?sync=true&limit=100' \
  -H "Authorization: Bearer $TALKI_API_KEY"

{
  "data": [],
  "next_cursor": null,
  "has_more": false
}

When data is non-empty, store next_cursor even if has_more is false: with sync=true it is your position, not a pointer to more data. Pass it back unchanged on the next poll. A sync cursor is refused in the default list.

Appointments, contacts, services, resources and unresolved requests use the same loop without a sync flag. See Core concepts.

5. Trigger a call in the sandbox

Ask the sandbox to have had a call and the post-call flow runs: the call record is written, the appointment is booked under the same capacity rules as any booking, a caller who gives a name is proposed as a pending contact, and signed webhooks are delivered to your endpoint.

Set up your receiver first — Agente → Integrazioni → Webhooks in the Talki app, logged in as the sandbox — and save the whsec_… signing secret.

localhost will not work

Loopback, private, link-local and CGNAT destinations are refused at registration and again at delivery. Use a public HTTPS tunnel while developing.

List the available scenarios:

curl --fail-with-body https://api.talki.it/v1/sandbox/scenarios \
  -H "Authorization: Bearer $TALKI_API_KEY"

[
  {
    "key": "booking_created",
    "description": "A caller books an appointment. The agent finds a slot and confirms it.",
    "events": ["call.ringing", "call.ended", "appointment.created"],
    "duration_seconds": 74
  }
]

The events array is part of the contract: assert that those events arrive. The call can send others too, such as pending_contact.created; see Sandbox.

curl --fail-with-body -X POST https://api.talki.it/v1/sandbox/calls \
  -H "Authorization: Bearer $TALKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario": "booking_created", "caller_phone": "+393480000001"}'

Verify X-Talki-Signature against the raw body before parsing it. The Webhooks guide has Node.js and Python examples.

6. Reset the sandbox

curl --fail-with-body -X POST https://api.talki.it/v1/sandbox/reset \
  -H "Authorization: Bearer $TALKI_API_KEY"

The history comes from a fixed seed, so it is identical every time and assertions against it hold across runs. Your credentials, your app’s installation and the sandbox’s services survive. Your webhook endpoints do not: register them again after a reset.

See Sandbox for the full scenario list and what each one emits.