Developer guide

This guide shows how to use the End Users API alongside the Conversations API to build context-aware, authenticated custom channel integrations. It covers setting user context before the first AI Agent turn, passing sensitive metadata securely, and common integration patterns.

Channel eligibility

• Native chat: The Chat SDK provides setSensitiveMetaFields() as the primary path. PATCH /v2/end-users/:id with sensitive_metadata is also available if you have the end_user_id.
• Social and email channels: PATCH /v2/end-users/:id with sensitive_metadata is the only API pathway. Obtain the end_user_id from a v1.end_user.created or v1.conversation.created webhook event.

Before you begin

• An API token
• A custom channel configured in the Ada dashboard
• A webhook endpoint (optional, for receiving events)

Multi-language support from the first turn

This example creates an end user with a language preference and metadata before starting a conversation. The AI Agent receives the correct language and context from the greeting onward.

$
curl -X POST https://EXAMPLE.ada.support/api/v2/end-users/ \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "profile": {
>
      "first_name": "Maria",
>
      "last_name": "Santos",
>
      "language": "pt-BR",
>
      "metadata": {
>
        "region": "latam",
>
        "plan_type": "enterprise"
>
      }
>
    }
>
  }'

1
{
2
  "end_user_id": "67a8b2c1d3f4e5a6b7c8d9e0",
3
  "profile": {
4
    "first_name": "Maria",
5
    "last_name": "Santos",
6
    "language": "pt-BR",
7
    "metadata": {
8
      "region": "latam",
9
      "plan_type": "enterprise"
10
    },
11
    ...
12
  },
13
  "created_at": "2026-03-31T10:30:00.000Z",
14
  "updated_at": "2026-03-31T10:30:00.000Z"
15
}

$
curl -X POST https://EXAMPLE.ada.support/api/v2/conversations/ \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "channel_id": "YOUR_CHANNEL_ID",
>
    "end_user_id": "67a8b2c1d3f4e5a6b7c8d9e0"
>
  }'

The AI Agent now has full user context from the first turn. Language is set to pt-BR, knowledge base lookups use the correct locale, and metadata values like region and plan_type are available as metavariables in Playbooks, Actions, and article rules.

Authenticated Actions without re-login

This example passes an auth token securely at user creation time so the AI Agent can run authenticated Actions (such as account lookups or order changes) without prompting the end user to log in again.

$
curl -X POST https://EXAMPLE.ada.support/api/v2/end-users/ \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "profile": {
>
      "language": "en-US",
>
      "metadata": {
>
        "account_tier": "premium"
>
      },
>
      "sensitive_metadata": {
>
        "fields": {
>
          "auth_token": "eyJhbGciOiJIUzI1NiIs...",
>
          "session_id": "sess_abc123"
>
        }
>
      }
>
    }
>
  }'

$
curl -X POST https://EXAMPLE.ada.support/api/v2/conversations/ \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "channel_id": "YOUR_CHANNEL_ID",
>
    "end_user_id": "END_USER_ID_FROM_STEP_1"
>
  }'

$
curl -X PATCH https://EXAMPLE.ada.support/api/v2/end-users/END_USER_ID \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "profile": {
>
      "sensitive_metadata": {
>
        "fields": {
>
          "auth_token": "eyJhbGciOiJSUzI1NiIs..."
>
        }
>
      }
>
    }
>
  }'

Campaign-driven personalization

This example sets campaign context on an end user so the AI Agent can personalize the greeting and route the conversation based on the campaign that brought the user in.

$
curl -X POST https://EXAMPLE.ada.support/api/v2/end-users/ \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "profile": {
>
      "metadata": {
>
        "campaign_id": "spring_2026_promo",
>
        "offer_code": "SAVE20",
>
        "source_channel": "email"
>
      }
>
    }
>
  }'

$
curl -X POST https://EXAMPLE.ada.support/api/v2/conversations/ \
>
  -H "Authorization: Bearer YOUR_API_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "channel_id": "YOUR_CHANNEL_ID",
>
    "end_user_id": "END_USER_ID_FROM_STEP_1"
>
  }'

Security considerations

sensitive_metadata vs. metadata

Use sensitive_metadata for any value that should not persist long-term or be visible to operators and LLMs. Use standard metadata for non-sensitive context that should be readable and persistent.

End-user scoped storage

sensitive_metadata values are stored at the end-user level, not the conversation level. If an end user has multiple active conversations, a value set in one conversation is accessible in all of them.

For the most common integration pattern (one end user per conversation), this is not observable. For integrations where a single end user has concurrent conversations across channels, be aware that sensitive values propagate to all active conversations for that end user.

Write-only behavior

sensitive_metadata values are never returned in API responses. If your integration needs to reference a token it previously set, store it on your side. Ada stores the value only for use by the AI Agent during the conversation.

FAQ

1
{
2
  "profile": {
3
    "sensitive_metadata": {
4
      "fields": {
5
        "auth_token": null
6
      }
7
    }
8
  }
9
}