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 a short-lived embed session credential. Create it from your backend with an API token; never expose the API token to the browser.

Create an embed session

Create a session for the employee whose access the embed should use:

curl https://api.getmateo.com/v1/embed-sessions \
  --request POST \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01" \
  --header "Content-Type: application/json" \
  --data '{
    "employee_id": "<employee_id>",
    "components": {
      "conversations": {
        "enabled": true
      }
    }
  }'

The response contains a credential that expires after 15 minutes:

{
  "client_secret": "<client_secret>",
  "expires_at": "2026-06-01T12:15:00.000Z",
  "components": {
    "conversations": {
      "enabled": true,
    },
  },
}

Treat client_secret as a bearer credential. Do not include it in logs, analytics events, or source control. Create a new session when it expires.

Embed the full inbox

Use the session credential as the access token in your iframe URL:

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

The embedded inbox uses the permissions of the employee selected when the session 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=<client_secret>

For example:

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

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 short-lived client_secret only for the embed URL, and expose that URL only to the intended signed-in employee. An API token cannot authenticate an embedded inbox.