Embed Inbox

Use the hellomateo embed to keep customer conversations inside an ERP, CRM, or internal dashboard. You can show the full inbox or limit the view to one conversation.

The embed uses an employee access token. This is different from the API token used to look up conversations.

Create an employee access token

In hellomateo:

1. Go to Settings → Integrations → Employee Tokens.
2. Select Create Employee Token.
3. Enter a name, select the employee whose access the embed should use, and create the token.
4. Copy the token immediately. It is shown only once.

Treat the employee token as a credential. Do not include it in public links, logs, analytics events, or source control. Revoke and replace it if it is exposed.

Embed the full inbox

Use this URL as the source of an iframe in your internal application:

https://app.getmateo.com/embed/conversations?access_token=<employee_token>

The embedded inbox uses the permissions of the employee selected when the token was created.

Embed one conversation

The single-conversation URL requires the hellomateo conversation ID:

https://app.getmateo.com/embed/conversations/<conversation_id>/single?access_token=<employee_token>

For example:

https://app.getmateo.com/embed/conversations/018f2f82-4f7a-7a2f-9c4e-0123456789ab/single?access_token=<employee_token>

Find a conversation for a contact

If your system stores the contact's external ID, use it to list that contact's conversations. Run this request in your backend so the API token is never exposed to the browser:

curl --get https://api.getmateo.com/v1/conversations \
  --data-urlencode "contact_external_id=customer-1001" \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01"

The response uses the standard list envelope:

{
  "object": "list",
  "data": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
      "contact_id": "018f2f82-4f7a-7a2f-9c4e-abcdef012345",
      "channel_id": "018f2f82-4f7a-7a2f-9c4e-fedcba987654",
      "inbox_id": "018f2f82-4f7a-7a2f-9c4e-456789abcdef",
      "status": "open",
    },
  ],
  "next_page_url": null,
  "previous_page_url": null,
}

A contact can have more than one conversation. Select the appropriate result by fields such as channel_id, inbox_id, and status, and follow next_page_url when it is present. Insert the selected conversation id into the single-conversation embed URL.

See List Conversations for all available filters and the complete response schema.

Keep credentials separate

Use an API token only for server-side API requests. Use the employee access token only for the embed URL, and expose that URL only to the intended signed-in employee. A public API token cannot authenticate an embedded inbox.