> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Optionally store third-party provider keys in OneInbox (BYOK).

## What is an integration?

An **integration** is a third-party API key stored securely inside OneInbox.

* OneInbox **encrypts** the key at rest
* The raw key is **never** returned after creation
* You reference integrations by `id` in other API calls

***

## When to use

Integrations are **entirely optional**. OneInbox provides defaults for everything out of the box — LLM, STT, TTS, and phone numbers — so you can build and test without any integration at all.

Add one only when you want to bring your own:

* **LLM** — **openai**, **shisa**, and **custom** (via `custom_websocket_url`) are available out of the box, no key needed. **anthropic** and **groq** require you to bring your own API key and create an integration first.
* **STT** — all providers (**deepgram**, **whisper**, **assembly\_ai**, **azure**) are available out of the box. Add an integration only if you want usage billed to your own provider account.
* **TTS** — all providers (**cartesia**, **deepgram**, **elevenlabs**, **openai**, **shisa**, **minimax**) are available out of the box. Add an integration only if you want usage billed to your own provider account.
* **Phone numbers** — use a number from your own Twilio or Telnyx account instead of the OneInbox default
* **Email or calendar tools** — `send_email` and `schedule_calendar_event` need a `credential_id` pointing at your Resend/SendGrid or Cal.com account

***

## How to use

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Production",
    "provider": "openai",
    "api_key": "<your_provider_api_key>"
  }'
```

Email, telephony, and calendar providers also take a `metadata` object with provider-specific details:

```bash theme={null}
# Email (Resend / SendGrid) — needs a verified "from" address
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Resend Email",
    "provider": "resend",
    "api_key": "<your_resend_api_key>",
    "metadata": { "from_email": "hello@yourdomain.com" }
  }'
```

```bash theme={null}
# Twilio — needs the phone number you bought with them + SIP trunk config
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Twilio Account",
    "provider": "twilio",
    "api_key": "<your_twilio_auth_token>",
    "metadata": {
      "account_sid": "<your_twilio_account_sid>",
      "phone_number": "+15739693824",
      "sip_trunk": "<your_sip_trunk_domain>"
    }
  }'
```

```bash theme={null}
# Cal.com — API key only; event_type_id is set on the tool, not the integration
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cal.com Bookings",
    "provider": "calcom",
    "api_key": "<your_calcom_api_key>"
  }'
```

***

## Resend setup

To use the `send_email` tool with Resend, you need two things: a Resend API key and a verified sending domain.

### 1 — Get your Resend API key

1. Go to [resend.com](https://resend.com) and log in
2. Open **API Keys** in the left sidebar
3. Click **Create API Key** — give it a name like "OneInbox"
4. Copy the key (starts with `re_`)

### 2 — Verify your sending domain

Resend blocks email from domains you haven't verified — sends fail with HTTP 403.

1. In Resend, go to **Domains** → **Add Domain**
2. Enter the domain you want to send from (e.g. `yourdomain.com`)
3. Resend shows you DNS records to add — typically three records:

| Type    | Purpose                                                                     |
| ------- | --------------------------------------------------------------------------- |
| `TXT`   | SPF — tells receiving servers that Resend is allowed to send on your behalf |
| `CNAME` | DKIM — cryptographically signs outgoing messages to prove they're genuine   |
| `CNAME` | DMARC alignment (optional but recommended)                                  |

4. Add these records in your DNS provider (GoDaddy, Cloudflare, Route 53, etc.)
5. Click **Verify** in Resend — propagation usually takes a few minutes

<Note>
  You can only send from the **exact domain** (or a subdomain of it) that you verified. For example, verifying `yourdomain.com` lets you send from `hello@yourdomain.com` or `noreply@yourdomain.com`. It does **not** cover `mail.yourdomain.com` unless you verify that subdomain separately.
</Note>

### 3 — Create the integration

Pass your verified sending address as `metadata.from_email`. This is the address that appears in the "From" field of every email the agent sends:

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Resend Email",
    "provider": "resend",
    "api_key": "<your_resend_api_key>",
    "metadata": { "from_email": "hello@yourdomain.com" }
  }'
```

Save the returned `id` — use it as `credential_id` when creating a `send_email` tool.

***

## Cal.com setup

To use the `schedule_calendar_event` tool, you need a Cal.com API key and the ID of the event type you want the agent to book against.

### What is an event type?

An event type in Cal.com is a bookable meeting — it defines the duration, availability, booking form, and confirmation settings. Examples:

| Event type     | Duration | Use case                                |
| -------------- | -------- | --------------------------------------- |
| Product Demo   | 30 min   | Agent books a demo for interested leads |
| Discovery Call | 20 min   | First-touch qualification call          |
| Onboarding     | 60 min   | New customer setup session              |

Each event type has a numeric ID that you pass to OneInbox.

### 1 — Get your Cal.com API key

1. Log in to [cal.com](https://cal.com)
2. Go to **Settings** → **Developer** → **API Keys**
3. Click **Add** — give it a name and copy the key

### 2 — Find your event type ID

**From the URL:** In your Cal.com dashboard, open **Event Types** and click Edit on the event you want. The URL contains the ID:

```
https://app.cal.com/event-types/123456
                                ^^^^^^
                                This is your event_type_id
```

**From the API:**

```bash theme={null}
curl "https://api.cal.com/v2/event-types" \
  -H "Authorization: Bearer <your_calcom_api_key>"
```

The response lists all your event types with their `id` fields. Pick the one you want the agent to book.

### 3 — Configure availability

The agent can only book slots that are available in Cal.com. Before going live:

* Set your **working hours** on the event type (e.g. Mon–Fri, 9am–5pm)
* Choose a **buffer time** between meetings if needed
* Make sure the event type is set to **active** (not draft)

If a caller asks for a time outside your availability, the booking fails with HTTP 400 and the agent will tell the caller that slot isn't available.

<Note>
  The agent must collect the caller's **name and email** during the conversation — both are required by Cal.com to complete a booking. Make sure your agent's system prompt asks for these before attempting to schedule.
</Note>

### 4 — Create the integration

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cal.com Bookings",
    "provider": "calcom",
    "api_key": "<your_calcom_api_key>"
  }'
```

Save the returned `id` — use it as `credential_id` when creating a `schedule_calendar_event` tool. The `event_type_id` is set on the tool itself, not the integration.

<Tip>
  If you run multiple event types (demo, discovery, onboarding), create a **separate integration for each** — each one points to a different `event_type_id`. Then create a separate `schedule_calendar_event` tool per integration, each with a clear description so the agent fires the right one based on what the caller asks for.
</Tip>

***

## How integrations connect

```
Integration (optional BYOK)
        │
        ▼
LLM model with matching "provider"
        │
        ▼
Agent (llm_id) → Calls
```

Telephony integrations power [Phone numbers](/guides/phone-calls) via `credential_id` on number search/register.

***

## Manage integrations

### List all integrations

```bash theme={null}
curl https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>"
```

### Get an integration

```bash theme={null}
curl https://api.oneinbox.ai/v1/integrations/<credential_id> \
  -H "Authorization: Bearer <api_key>"
```

The raw `api_key` is never returned — only the `masked_key` is shown.

### Update an integration

Update the name, API key, metadata, or provider of an existing integration.

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/integrations/<credential_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Updated",
    "api_key": "<new_api_key>"
  }'
```

### Delete an integration

Permanently removes the stored credential. Any models or tools using this `credential_id` will lose access to the provider until you attach a new integration.

```bash theme={null}
curl -X DELETE https://api.oneinbox.ai/v1/integrations/<credential_id> \
  -H "Authorization: Bearer <api_key>"
```

***

## Next steps

* **[Phone numbers](/guides/phone-calls)** — telephony integration
* **[Voices](/guides/voices)** — custom voice import
* **[Create integration](/api-reference/integrations/create-integration)** — API reference