Add metadata for a webchat contact

curl --request POST \
  --url https://api.vambe.me/api/public/webchat/contact/add-metadata \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "metadata": {},
  "externalUserId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {}, externalUserId: '<string>'})
};

fetch('https://api.vambe.me/api/public/webchat/contact/add-metadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vambe.me/api/public/webchat/contact/add-metadata"

payload = {
    "metadata": {},
    "externalUserId": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

POST

api

public

webchat

contact

add-metadata

Add metadata for a webchat contact

curl --request POST \
  --url https://api.vambe.me/api/public/webchat/contact/add-metadata \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "metadata": {},
  "externalUserId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {}, externalUserId: '<string>'})
};

fetch('https://api.vambe.me/api/public/webchat/contact/add-metadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vambe.me/api/public/webchat/contact/add-metadata"

payload = {
    "metadata": {},
    "externalUserId": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Webchat Contacts Only: This endpoint is specifically for contacts from your web chat widget. For other channels, use POST /api/public/contact/ /update-metadata.

Overview

Add or update metadata for a webchat contact using their external user ID. This endpoint is designed specifically for web chat widget integrations where you may have your own user identification system. Unlike the general metadata endpoint, this one identifies contacts by your externalUserId rather than the Vambe contact ID.

Use Cases

User Profile Enrichment: Add user data from your system to webchat contacts
Session Data: Store information about user sessions and interactions
External System Sync: Sync user data from your database to Vambe
Custom Tracking: Add custom tracking fields for webchat visitors
User Identification: Link webchat conversations to your user IDs

Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

x-api-key: your_api_key_here

Request Body

Field	Type	Required	Description
`externalUserId`	string	Yes	Your unique identifier for the webchat user
`metadata`	object	Yes	Key-value pairs of metadata to add/update

External User ID: This must match the externalUserId you provided when initializing the webchat widget or creating the contact.

Response Structure

Returns the updated contact metadata.

Example Request

curl --request POST \
  'https://api.vambe.me/api/public/webchat/contact/add-metadata' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "externalUserId": "user-12345",
    "metadata": {
      "subscription_tier": "premium",
      "account_status": "active",
      "lifetime_value": "5000",
      "registration_date": "2024-01-15",
      "preferred_language": "es",
      "location": "Santiago, Chile"
    }
  }'

Example Response

{
  "success": true,
  "updated_fields": 6
}

Common Use Cases

1. Add User Profile Data

const enrichWebchatContact = async (externalUserId, userProfile) => {
  const response = await fetch(
    'https://api.vambe.me/api/public/webchat/contact/add-metadata',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        externalUserId: externalUserId,
        metadata: {
          user_name: userProfile.name,
          email: userProfile.email,
          account_type: userProfile.accountType,
          member_since: userProfile.joinDate,
          total_purchases: userProfile.purchaseCount.toString(),
        },
      }),
    },
  );

  const result = await response.json();
  console.log('Webchat contact enriched with user profile');

  return result;
};

2. Track Session Information

const trackWebchatSession = async (externalUserId, sessionData) => {
  const response = await fetch(
    'https://api.vambe.me/api/public/webchat/contact/add-metadata',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        externalUserId: externalUserId,
        metadata: {
          session_start: sessionData.startTime,
          page_views: sessionData.pageViews.toString(),
          time_on_site: sessionData.duration.toString(),
          referrer: sessionData.referrer,
          device_type: sessionData.deviceType,
          browser: sessionData.browser,
        },
      }),
    },
  );

  return await response.json();
};

3. Sync from Your Database

const syncUserDataToWebchat = async (userId) => {
  // Get user from your database
  const user = await yourDatabase.getUserById(userId);

  // Sync to Vambe webchat contact
  const response = await fetch(
    'https://api.vambe.me/api/public/webchat/contact/add-metadata',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        externalUserId: user.id,
        metadata: {
          full_name: user.fullName,
          company: user.company,
          role: user.role,
          industry: user.industry,
          company_size: user.companySize,
          phone: user.phone,
          country: user.country,
        },
      }),
    },
  );

  console.log('User data synced to webchat contact');

  return await response.json();
};

Webchat External User ID

The externalUserId is typically set when:

Widget Initialization: Passed when initializing the webchat widget
User Login: Set when user authenticates on your website
Cookie/Session: Tracked via browser session or cookie

Example webchat initialization:

VambeChat.init({
  channelId: 'your-channel-id',
  externalUserId: 'user-12345', // Your user ID
  // ...
});

Metadata Processing

Unstructured Data: Metadata is processed with AI
Field Matching: Automatically maps to custom field definitions
All Fields Updated: Uses editAllFields: true mode
Flexible Schema: Accept any key-value pairs

Error Responses

Status Code	Description
400	Bad Request - Invalid metadata format
401	Unauthorized - Invalid or missing API key
404	Not Found - Contact not found with that user ID
500	Internal Server Error - Something went wrong

Important Notes

Webchat Only: This endpoint only works for webchat contacts
External User ID Required: Must match the ID used in webchat widget
Contact Must Exist: The webchat contact must already exist
Organization Scoped: Contact must belong to your organization
AI Processing: Metadata is processed with AI for field extraction

For Other Channels

If you need to update metadata for contacts from other channels (WhatsApp, Instagram, etc.), use the general metadata endpoint: General Metadata Endpoint:

POST /api/public/contact/{aiContactId}/update-metadata

View Documentation

POST /api/public/contact//update-metadata - General metadata update (all channels)
GET /api/public/contact//info - Get contact info including metadata
POST /api/public/customer/upsert/info - Create/update contacts with metadata

Webchat vs General Metadata

Feature	Webchat Metadata (This)	General Metadata
Identifier	externalUserId (your ID)	aiContactId (Vambe UUID)
Channel	Webchat only	All channels
Use When	Have external user ID	Have Vambe contact ID
Widget Integration	✅ Perfect for widgets	❌ Need contact ID lookup

Headers

x-api-key

string

required

API key needed to authorize the request

Body

application/json

metadata

object

externalUserId

string

Response

Message sent successfully.

⌘I

Contact Management

Tags & Labels

AI Run Logs

Tickets & Support

Team Management

Partners

Deprecated

Add metadata for a webchat contact

Overview

Use Cases

Authentication

Request Body

Response Structure

Example Request

Example Response

Common Use Cases

1. Add User Profile Data

2. Track Session Information

3. Sync from Your Database

Webchat External User ID

Metadata Processing

Error Responses

Important Notes

For Other Channels

Webchat vs General Metadata

Headers

Body

Response

​Overview

​Use Cases

​Authentication

​Request Body

​Response Structure

​Example Request

​Example Response

​Common Use Cases

​1. Add User Profile Data

​2. Track Session Information

​3. Sync from Your Database

​Webchat External User ID

​Metadata Processing

​Error Responses

​Important Notes

​For Other Channels

​Related Endpoints

​Webchat vs General Metadata

Headers

Body

Response

Overview

Use Cases

Authentication

Request Body

Response Structure

Example Request

Example Response

Common Use Cases

1. Add User Profile Data

2. Track Session Information

3. Sync from Your Database

Webchat External User ID

Metadata Processing

Error Responses

Important Notes

For Other Channels

Related Endpoints

Webchat vs General Metadata