Skip to main content
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>"
}
'
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

FieldTypeRequiredDescription
externalUserIdstringYesYour unique identifier for the webchat user
metadataobjectYesKey-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.ai/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.ai/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.ai/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.ai/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:
  1. Widget Initialization: Passed when initializing the webchat widget
  2. User Login: Set when user authenticates on your website
  3. 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 CodeDescription
400Bad Request - Invalid metadata format
401Unauthorized - Invalid or missing API key
404Not Found - Contact not found with that user ID
500Internal 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

​
Webchat vs General Metadata

FeatureWebchat Metadata (This)General Metadata
IdentifierexternalUserId (your ID)aiContactId (Vambe UUID)
ChannelWebchat onlyAll channels
Use WhenHave external user IDHave 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.