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

# Embed Inbox

> Learn how to embed your customer chats directly into your own systems like ERP, CRM, or internal dashboard.

With the **hellomateo Embed**, you can integrate your customer chats directly into your own systems — for example, your **ERP**, **CRM**, or **internal dashboard**.
This makes communication faster, easier, and keeps your team in one workspace.

## 🧭 Two ways to show your inbox

You can embed either **a single conversation** or **your entire inbox**.

### Option 1: Single conversation

Show only one customer chat — perfect for displaying the chat directly in your ERP next to a contact.

👉 **URL format:**

```
https://app.getmateo.com/embed/conversations/<conversation_id>/single
```

### Option 2: Full inbox

Display all your conversations in one view.

👉 **URL:**

```
https://app.getmateo.com/embed/conversations
```

To make it work, simply **add your employee access token** at the end of the URL:

```
?access_token=<employee_token>
```

✅ **Examples:**

**Single conversation:**

```
https://app.getmateo.com/embed/conversations/12345/single?access_token=abcd1234
```

**Full inbox:**

```
https://app.getmateo.com/embed/conversations?access_token=abcd1234
```

## 🧩 How to get the conversation for a contact

If you want to show the chat for a specific customer, you'll need their **conversation ID**.
Here's how to find it via the API (for example, using the `external_id`):

### 1️⃣ Get the conversation by external ID

```bash theme={null}
curl --request GET   --url "https://integration.getmateo.com/api/v1/contact?external_id=eq.<external_id>&select=conversation(id)"   --header "Authorization: Bearer <token>"
```

You'll receive a `conversation.id` in the response — use it in your embed link.

## 🔑 Create an Employee Token

If you don't have an employee token yet, you can create one in your hellomateo account:

1. Go to **Settings → Integrations → Employee Tokens**
2. Click **Create Employee Token**
3. Enter a **token name**, select the **employee**, and click **Create Token**
4. Copy and save the token — it will **only be shown once**

## 📧 Pre-filling Conversations via URL

You can now create links that automatically pre-fill conversation recipients. Users will review and confirm before sending.

### URL Format

```
https://[your-domain]/conversations/new?channel_id=[CHANNEL_ID]&handle=[RECIPIENT1,RECIPIENT2,...]
```

### Required Parameters

* `channel_id`: The UUID of your channel (get this from your channel settings)
* `handle`: Comma-separated recipient handles (phone, email, etc.)

### ⚠️ Important: URL Encoding

**Special characters MUST be encoded:**

| Character   | Encoded As                        |
| ----------- | --------------------------------- |
| `+` (plus)  | `%2B`                             |
| Space       | `%20`                             |
| `@` (at)    | `%40`                             |
| `,` (comma) | `%2C` (optional, but recommended) |

Please note that if you don't want to encode it manually (recommended), then enter the handles normally with the symbols and let the AI encode ONLY THE PARAMATERS and not the whole url

## Working Examples

### Single Recipient - Phone with `+` (Encoded)

```
https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678
```

### Single Recipient - Phone without `+`

```
https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=4915212345678
```

### Single Recipient - Email (Encoded)

```
https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=kunde%40beispiel.de
```

### Single Recipient - Handle with Spaces (Encoded)

```
https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=my%20custom%20handle
```

### Multiple Recipients - Broadcast Mode (2 recipients)

```
https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678,%2B4917612398765
```

### Multiple Recipients - Broadcast Mode (3 recipients)

```
https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678,%2B4917612398765,%2B4916023456789
```

### Multiple Recipients - Mixed Formats

```
https://app.getmateo.com/conversations/new?channel_id=9646acea-f031-4522-ae7f-03932e42e619&handle=%2B4915212345678,4917612398765,004916023456789
```

### Multiple Recipients - Emails (5 recipients)

```
https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=kunde1%40beispiel.de,kunde2%40beispiel.de,support%40firma.com,info%40test.de,kontakt%40company.de
```

### Multiple Recipients - With Spaces (Encoded)

```
https://app.getmateo.com/conversations/new?channel_id=abc123-def456-789&handle=user%20one,user%20two,user%20three
```

## ❌ Common Mistakes

**Don't use unencoded special characters:**

```
❌ handle=+4915212345678,+4917612398765     (+ will be lost)
❌ handle=kunde@beispiel.de                  (may break the URL)
❌ handle=my custom handle                   (spaces will break the URL)
```

**Always encode:**

```
✅ handle=%2B4915212345678,%2B4917612398765
✅ handle=kunde%40beispiel.de
✅ handle=my%20custom%20handle
```