Update all the tags from an AI contact

Overview

Update (replace) all tags for a specific contact. This endpoint completely replaces the contact’s current tags with a new set of tag IDs. Use this when you want to set the exact tag list for a contact. Tags help you organize, filter, and segment contacts based on characteristics, behaviors, or any custom criteria relevant to your business.

Use Cases

Contact Categorization: Organize contacts by customer type, status, or segment
Workflow Automation: Update tags based on customer actions or events
Data Sync: Sync tags from external CRM systems
Bulk Updates: Programmatically update contact tags in batch operations
Customer Journey: Tag contacts as they progress through your funnel
Segmentation: Create dynamic segments based on tag combinations

Authentication

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

x-api-key: your_api_key_here

Path Parameters

Parameter	Type	Required	Description
`aiContactId`	string (UUID)	Yes	Unique identifier of the contact

Request Body

Field	Type	Required	Description
`tagsIds`	number[]	Yes	Array of tag IDs to assign to the contact

Response Structure

Field	Type	Description
`status`	string	Status of the operation (always “success”)
`aiContactTagsLength`	number	Total number of tags assigned to the contact

Example Request

curl --request PATCH \
  'https://api.vambe.ai/api/public/contact/tags/1937bd2c-a13c-4365-af06-43af9a988e36' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '{
    "tagsIds": [1, 5, 12, 23]
  }'

Example Response

{
  "status": "success",
  "aiContactTagsLength": 4
}

Common Use Cases

1. Replace All Contact Tags

const updateContactTags = async (contactId, tagIds) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        tagsIds: tagIds,
      }),
    },
  );

  const result = await response.json();
  console.log(`Contact now has ${result.aiContactTagsLength} tags`);
  return result;
};

// Usage
updateContactTags('contact-uuid', [1, 5, 12]);

2. Remove All Tags from Contact

const removeAllTags = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        tagsIds: [], // Empty array removes all tags
      }),
    },
  );

  const result = await response.json();
  console.log('All tags removed from contact');
  return result;
};

3. Update Tags Based on Customer Behavior

const updateTagsBasedOnPurchase = async (contactId, purchaseAmount) => {
  // Define tag IDs for different customer tiers
  const TAG_IDS = {
    customer: 1,
    vip: 5,
    high_value: 12,
    repeat_buyer: 23,
  };

  let tags = [TAG_IDS.customer, TAG_IDS.repeat_buyer];

  // Add VIP tag if purchase is over $500
  if (purchaseAmount > 500) {
    tags.push(TAG_IDS.vip, TAG_IDS.high_value);
  }

  const response = await fetch(
    `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        tagsIds: tags,
      }),
    },
  );

  return await response.json();
};

4. Sync Tags from External CRM

const syncTagsFromCRM = async (contactId, externalTags) => {
  // Map external tag names to your Vambe tag IDs
  const tagMapping = {
    'hot-lead': 1,
    'cold-lead': 2,
    qualified: 5,
    'needs-followup': 12,
  };

  const tagIds = externalTags
    .map((tagName) => tagMapping[tagName])
    .filter((id) => id !== undefined);

  const response = await fetch(
    `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        tagsIds: tagIds,
      }),
    },
  );

  return await response.json();
};

// Usage
syncTagsFromCRM('contact-uuid', ['hot-lead', 'qualified']);

5. Bulk Tag Update for Multiple Contacts

const bulkUpdateTags = async (contactIds, tagIds) => {
  const results = [];

  for (const contactId of contactIds) {
    try {
      const response = await fetch(
        `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
        {
          method: 'PATCH',
          headers: {
            'Content-Type': 'application/json',
            'x-api-key': 'your_api_key_here',
          },
          body: JSON.stringify({
            tagsIds: tagIds,
          }),
        },
      );

      const result = await response.json();
      results.push({ contactId, success: true, ...result });
    } catch (error) {
      results.push({ contactId, success: false, error: error.message });
    }
  }

  console.log(
    `Updated ${results.filter((r) => r.success).length} of ${contactIds.length} contacts`,
  );

  return results;
};

6. Add Tag Without Removing Existing Ones

// First get current tags, then add new one
const addTagToContact = async (contactId, newTagId) => {
  // Get current contact info to see existing tags
  const contactResponse = await fetch(
    `https://api.vambe.ai/api/public/contact/${contactId}/info`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const contact = await contactResponse.json();

  // Get current tag IDs (you'll need to extract from contact.tags)
  const currentTagIds = contact.tags?.map((t) => t.tag_id) || [];

  // Add new tag if not already present
  if (!currentTagIds.includes(newTagId)) {
    currentTagIds.push(newTagId);
  }

  // Update with combined list
  const response = await fetch(
    `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        tagsIds: currentTagIds,
      }),
    },
  );

  return await response.json();
};

Important Behavior

⚠️ Replaces All Tags

This endpoint replaces the contact’s tags completely. If a contact has tags [1, 2, 3] and you send tagsIds: [4, 5], the contact will end up with only [4, 5]. Before: Contact has tags [1, 2, 3] Request: { "tagsIds": [4, 5] } After: Contact has tags [4, 5]

Adding vs Replacing

To add a tag: First get existing tags, append new ID, then update
To remove a tag: Get existing tags, filter out the unwanted ID, then update
To replace all: Simply send the new list (this endpoint)

Tag ID Requirements

All tag IDs must exist in your organization
All tag IDs must belong to your account
Invalid tag IDs will cause the request to fail with a 400 error
Tag IDs are numeric integers, not UUIDs

Error Responses

Status Code	Description
400	Bad Request - Invalid tag IDs or tags don’t exist
401	Unauthorized - Invalid or missing API key
404	Not Found - Contact not found
500	Internal Server Error - Something went wrong

Getting Tag IDs

To get available tag IDs for your organization, use the Get All Tags endpoint:

GET /api/public/tags

View Documentation This returns all your tags with their IDs, names, types, and colors. Workflow:

Call GET /api/public/tags to get all available tags
Find the tag IDs you need (by name or other criteria)
Use those IDs with this endpoint to update contact tags

Best Practices

1. Validate Tag IDs Before Updating

const validateAndUpdateTags = async (contactId, tagIds) => {
  // Ensure tag IDs are numbers
  const validTagIds = tagIds.filter((id) => typeof id === 'number' && id > 0);

  if (validTagIds.length !== tagIds.length) {
    console.warn('Some tag IDs were invalid and removed');
  }

  return await updateContactTags(contactId, validTagIds);
};

2. Handle Errors Gracefully

const safeUpdateTags = async (contactId, tagIds) => {
  try {
    const result = await fetch(
      `https://api.vambe.ai/api/public/contact/tags/${contactId}`,
      {
        method: 'PATCH',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': 'your_api_key_here',
        },
        body: JSON.stringify({ tagsIds: tagIds }),
      },
    );

    if (!result.ok) {
      throw new Error(`HTTP ${result.status}: ${await result.text()}`);
    }

    return await result.json();
  } catch (error) {
    console.error('Failed to update tags:', error);
    throw error;
  }
};

3. Remove Duplicates

const updateWithUniqueTags = async (contactId, tagIds) => {
  // Remove duplicate tag IDs
  const uniqueTagIds = [...new Set(tagIds)];

  return await updateContactTags(contactId, uniqueTagIds);
};

GET /api/public/tags - Get all available tags and their IDs
POST /api/public/channels///tags - Create and assign tags using phone/username
GET /api/public/contact//info - Get contact info including current tags

Tag Types

Tags can be of two types:

CONTACT Tags: Associated with the contact permanently
TICKET Tags: Only assigned when a contact has an active ticket

When using this endpoint, both types can be updated, but TICKET tags will only appear when the contact has an active ticket.

Notes

Atomic Operation: The tag update is atomic - either all tags are updated or none
No Partial Updates: You cannot update tags one at a time with this endpoint
Immediate Effect: Changes take effect immediately
Activity Logged: Tag changes are logged in the contact’s activity history

Headers

x-api-key

string

required

API key required to authorize the request

Path Parameters

aiContactId

string

required

ID of the AI contact

Body

application/json

tagsIds

number[]

Response

Tags updated successfully.

Contact Management

Tags & Labels

Conversations

Tickets & Support

Team Management

Update all the tags from an AI contact

Overview

Use Cases

Authentication

Path Parameters

Request Body

Response Structure

Example Request

Example Response

Common Use Cases

1. Replace All Contact Tags

2. Remove All Tags from Contact

3. Update Tags Based on Customer Behavior

4. Sync Tags from External CRM

5. Bulk Tag Update for Multiple Contacts

6. Add Tag Without Removing Existing Ones

Important Behavior

⚠️ Replaces All Tags

Adding vs Replacing

Tag ID Requirements

Error Responses

Getting Tag IDs

Best Practices

1. Validate Tag IDs Before Updating

2. Handle Errors Gracefully

3. Remove Duplicates

Tag Types

Notes

Headers

Path Parameters

Body

Response

Contact Management

Tags & Labels

Conversations

Tickets & Support

Team Management

​Overview

​Use Cases

​Authentication

​Path Parameters

​Request Body

​Response Structure

​Example Request

​Example Response

​Common Use Cases

​1. Replace All Contact Tags

​2. Remove All Tags from Contact

​3. Update Tags Based on Customer Behavior

​4. Sync Tags from External CRM

​5. Bulk Tag Update for Multiple Contacts

​6. Add Tag Without Removing Existing Ones

​Important Behavior

​⚠️ Replaces All Tags

​Adding vs Replacing

​Tag ID Requirements

​Error Responses

​Getting Tag IDs

​Best Practices

​1. Validate Tag IDs Before Updating

​2. Handle Errors Gracefully

​3. Remove Duplicates

​Related Endpoints

​Tag Types

​Notes

Headers

Path Parameters

Body

Response

Overview

Use Cases

Authentication

Path Parameters

Request Body

Response Structure

Example Request

Example Response

Common Use Cases

1. Replace All Contact Tags

2. Remove All Tags from Contact

3. Update Tags Based on Customer Behavior

4. Sync Tags from External CRM

5. Bulk Tag Update for Multiple Contacts

6. Add Tag Without Removing Existing Ones

Important Behavior

⚠️ Replaces All Tags

Adding vs Replacing

Tag ID Requirements

Error Responses

Getting Tag IDs

Best Practices

1. Validate Tag IDs Before Updating

2. Handle Errors Gracefully

3. Remove Duplicates

Related Endpoints

Tag Types

Notes