Skip to main content
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:
  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:
CharacterEncoded 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