Embed Inbox - Hellomateo API Documentation

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

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:

Go to Settings → Integrations → Employee Tokens
Click Create Employee Token
Enter a token name, select the employee, and click Create Token
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

​🧭 Two ways to show your inbox

​Option 1: Single conversation

​Option 2: Full inbox

​🧩 How to get the conversation for a contact

​1️⃣ Get the conversation by external ID

​🔑 Create an Employee Token

​📧 Pre-filling Conversations via URL

​URL Format

​Required Parameters

​⚠️ Important: URL Encoding

​Working Examples

​Single Recipient - Phone with + (Encoded)

​Single Recipient - Phone without +

​Single Recipient - Email (Encoded)

​Single Recipient - Handle with Spaces (Encoded)

​Multiple Recipients - Broadcast Mode (2 recipients)

​Multiple Recipients - Broadcast Mode (3 recipients)

​Multiple Recipients - Mixed Formats

​Multiple Recipients - Emails (5 recipients)

​Multiple Recipients - With Spaces (Encoded)

​❌ Common Mistakes