---
title: "Quickstart"
description: "Connect your product to Voicetta in a few minutes. Receive a real conversation event, handle it in your backend, and read the same data through the API."
publishedAt: "2026-08-22"
modifiedAt: "2026-08-22"
category: "Getting Started"
tags: "Voicetta, quickstart, webhook, API key, curl, integration"
navOrder: "20"
canonical: "https://voicetta.com/developers/quickstart"
---

# Quickstart

Connect Voicetta to your product in a few minutes.

The basic flow is:

**Customer → Voicetta → your backend → your product**

Voicetta handles the conversation.

Your backend receives the event and decides what to do with it.

## Step 1: See a real event

Before writing code, send a test event to a temporary endpoint.

1. Open [webhook.site](https://webhook.site), RequestBin, or use an `ngrok` tunnel.
2. Copy the URL.
3. In Voicetta, open **Settings → Developers**.
4. Create a webhook endpoint using that URL.
5. Choose the events you want.
6. Click **Send test event**.

You will see the exact HTTP request, headers, and JSON payload.

A Voicetta event is one JSON object.

The basic shape is:

```json
{
  "event": "call.completed",
  "event_id": "9f8b1c4e-6d2a-4b7f-8e21-3c5a7d9e0f11",
  "version": 1,
  "occurred_at": "2026-08-20T10:03:00+00:00",
  "call": {}
}
```

The event tells you what happened.

The object underneath it contains the data.

## Step 2: Read data through the API

Create an API key in **Settings → Developers**.

```bash
curl -H "Authorization: Bearer vk_live_your_key_here" \
  "https://api.voicetta.com/v1/calls?limit=1"
```

You get a page of calls:

```json
{
  "calls": [
    {
      "call_id": "9f8b1c4e-6d2a-4b7f-8e21-3c5a7d9e0f11",
      "workspace_id": "2a1f8e7d-4c3b-4a29-9f18-6d5e4c3b2a19",
      "call_type": "inbound",
      "direction": "inbound",
      "status": "ended",
      "duration_seconds": 180,
      "analysis": {
        "summary": "Caller booked a double room for Friday."
      }
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOC0yMFQxMDowMDowMCswMDowMHw5ZjhiMWM0ZQ"
}
```

You can request only the fields your application needs:

```bash
curl -H "Authorization: Bearer vk_live_your_key_here" \
  "https://api.voicetta.com/v1/calls?limit=1&fields=transcript"
```

Requesting a field group your key does not have returns `403`.

A missing field is not an error. Fields with no value are omitted.

The other collections work the same way:

```bash
curl -H "Authorization: Bearer vk_live_your_key_here" \
  "https://api.voicetta.com/v1/messages?limit=1"

curl -H "Authorization: Bearer vk_live_your_key_here" \
  "https://api.voicetta.com/v1/threads?limit=1"
```

One API key can read all three collections.

## Step 3: Handle webhook events

Replace the temporary URL with your own endpoint.

A minimal Express handler:

```js
const HANDLERS = {
  'call.completed': (body) => store('call', body.call),
  'message.received': (body) => store('message', body.message),
  'message.sent': (body) => store('message', body.message),
  'thread.completed': (body) => store('thread', body.thread),
};

app.post('/voicetta/events', express.json(), (req, res) => {
  res.sendStatus(200);

  const deliveryId = req.get('X-Voicetta-Delivery-Id');

  if (alreadyProcessed(deliveryId)) {
    return;
  }

  const handler = HANDLERS[req.body.event];

  if (!handler) {
    return;
  }

  enqueue(deliveryId, () => handler(req.body));
});
```

The important part is the shape:

1. receive the event
2. acknowledge it
3. deduplicate it
4. dispatch based on `event`
5. process it in the background

Add signature verification before going to production.

See [Webhook Reference](/developers/webhooks#verifying-voicetta-requests).

## The two rules that matter

### Acknowledge first

Return `200` quickly.

Do not wait for database writes, API calls, or other processing before responding.

Put the event into a queue or store it, return `200`, and process it afterward.

If the response takes too long, Voicetta will retry the delivery.

### Expect duplicates

Webhook delivery is at-least-once.

A network problem can cause the same event to arrive more than once.

Make your handler idempotent.

Use `X-Voicetta-Delivery-Id` to identify delivery attempts, or use `event_id` when you want to treat repeated deliveries as the same conversation event.

## Step 4: Go live

1. Make sure your endpoint is publicly reachable over HTTPS.
2. Test the endpoint with **Send test event**.
3. Confirm that your server returns `200`.
4. Add signature verification.
5. Watch the delivery log.
6. Start receiving real traffic.

Enabling a webhook event is not retroactive.

If you need older conversations, use the REST API.

## Related pages

* [Overview](/developers/overview)
* [Webhook Reference](/developers/webhooks)
* [Message Events](/developers/message-events)
* [Thread Events](/developers/thread-events)
* [Read API Reference](/developers/api-reference)
* [n8n and No-code](/developers/n8n)