VoIPBin Documentation
Tag
Attach key-value tags to VoIPBIN resources for organization, filtering, and categorization.
API Reference: Tag endpoints
Overview
Note
AI Context
Complexity: Low
Cost: Free. Creating and managing tags incurs no charges.
Async: No.
POST /tagsreturns immediately with the created tag.
VoIPBIN’s Tag API provides a flexible labeling system for organizing and categorizing resources. Tags are primarily used for skill-based routing in queues, but can also categorize agents by teams, departments, languages, or any custom attribute.
With the Tag API you can:
Create and manage tags for categorization
Assign tags to agents for skill-based routing
Configure queue requirements based on tags
Filter and organize resources by tags
Build flexible routing strategies
Tag Matching
Queue routing uses tags to find qualified agents.
Matching Rules
Queue Requirements: Agent Skills:
+-------------------+ +-------------------+
| Tags: | | Tags: |
| o english | | o english |
| o billing | | o billing |
+-------------------+ | o vip_support |
| +-------------------+
| |
v v
+------------------------------------------+
| MATCH: Agent has ALL required tags |
| (extra tags like vip_support are OK) |
+------------------------------------------+
|
v
Agent is eligible!
Matching Examples
Example 1: MATCH
+--------------------------------------------+
| Queue requires: [english, billing] |
| Agent has: [english, billing, spanish] |
| Result: MATCH (has all required) |
+--------------------------------------------+
Example 2: NO MATCH
+--------------------------------------------+
| Queue requires: [english, billing] |
| Agent has: [english, tech_support] |
| Result: NO MATCH (missing "billing") |
+--------------------------------------------+
Example 3: MATCH
+--------------------------------------------+
| Queue requires: [english] |
| Agent has: [english, spanish, french] |
| Result: MATCH (has required tag) |
+--------------------------------------------+
Key Features and Use Cases
Tags enable various organizational and routing strategies.
Agent Skills
Agent: John Smith
+--------------------------------------------+
| Skills (Tags): |
| o english - Can communicate in English |
| o spanish - Can communicate in Spanish |
| o billing - Trained on billing issues |
| o tier2 - Senior support level |
+--------------------------------------------+
Team Assignment
Team Structure:
+--------------------------------------------+
| Sales Team: tag = "sales" |
| Support Team: tag = "support" |
| Billing Team: tag = "billing" |
| VIP Team: tag = "vip" |
+--------------------------------------------+
Language Routing
Language Tags:
+--------------------------------------------+
| english | spanish | french | german |
| japanese | korean | chinese | hindi |
+--------------------------------------------+
Queue: Spanish Support
Required Tags: [spanish, support]
-> Routes to agents with both tags
Skill-Based Routing
Incoming Call: Technical Issue (Spanish)
|
v
Queue: Tech Support Spanish
Required: [spanish, tech_support]
|
v
+--------------------------------------------+
| Available Agents: |
| Agent A: [english, tech_support] - NO |
| Agent B: [spanish, sales] - NO |
| Agent C: [spanish, tech_support] - YES |
+--------------------------------------------+
|
v
Route to Agent C
Tag Categories
Organize tags into logical categories.
Recommended Tag Structure
+-----------------------------------------------------------------------+
| Tag Categories |
+-----------------------------------------------------------------------+
Language Skills:
+-------------------+-------------------+-------------------+
| lang_english | lang_spanish | lang_french |
| lang_german | lang_japanese | lang_korean |
+-------------------+-------------------+-------------------+
Department/Team:
+-------------------+-------------------+-------------------+
| team_sales | team_support | team_billing |
| team_technical | team_retention | team_vip |
+-------------------+-------------------+-------------------+
Skill Level:
+-------------------+-------------------+-------------------+
| tier_1 | tier_2 | tier_3 |
| supervisor | manager | |
+-------------------+-------------------+-------------------+
Product Knowledge:
+-------------------+-------------------+-------------------+
| product_basic | product_premium | product_enterprise|
+-------------------+-------------------+-------------------+
Common Scenarios
Scenario 1: Multilingual Support Center
Route calls based on language preference.
Setup:
+--------------------------------------------+
| Tags: english, spanish, french, german |
| |
| Queues: |
| - English Support: [english, support] |
| - Spanish Support: [spanish, support] |
| - French Support: [french, support] |
| |
| Agents assigned appropriate language tags |
+--------------------------------------------+
Flow:
IVR: "Press 1 for English, 2 for Spanish..."
|
v
Route to appropriate language queue
Scenario 2: Tiered Support System
Escalate based on skill level.
Tier Structure:
+--------------------------------------------+
| Tier 1: Basic issues |
| Queue requires: [tier_1] |
| |
| Tier 2: Complex issues |
| Queue requires: [tier_2] |
| |
| Tier 3: Escalations |
| Queue requires: [tier_3, supervisor] |
+--------------------------------------------+
Escalation:
Tier 1 agent can't resolve
|
v
Transfer to Tier 2 queue
|
v
Agent with [tier_2] handles
Scenario 3: VIP Customer Routing
Priority routing for VIP customers.
VIP Detection:
+--------------------------------------------+
| Customer identified as VIP |
| (via caller ID or account lookup) |
| |
| Route to VIP Queue |
| Requires: [vip, senior_agent] |
| |
| Only experienced agents handle VIP calls |
+--------------------------------------------+
Best Practices
1. Naming Conventions
Use consistent naming (lowercase, underscores)
Keep names short but descriptive
Document what each tag means
2. Tag Assignment
Assign only relevant tags to agents
Review and update tags regularly
Train agents before assigning skill tags
Remove tags when no longer applicable
3. Queue Configuration
Don’t require too many tags (limits eligible agents)
Use minimum necessary tags for routing
Consider fallback queues with fewer requirements
4. Organization
Create a tag taxonomy document
Review tag usage periodically
Consolidate similar tags
Archive unused tags
Troubleshooting
Routing Issues
Symptom |
Solution |
|---|---|
No agents matched |
Check agents have ALL required tags; reduce queue tag requirements |
Wrong agents receiving calls |
Verify agent tag assignments; check queue tag requirements |
Agent not getting calls from queue |
Ensure agent has required tags; check agent status is “available” |
Tag Management Issues
Symptom |
Solution |
|---|---|
Tag assignment failed |
Verify tag IDs exist; check API permissions |
Duplicate tag error |
Tag names must be unique per customer; use existing tag instead |
Tag
Tag
{
"id": "<string>",
"name": "<string>",
"detail": "<string>",
"tm_create": "<string>",
"tm_update": "<string>",
"tm_delete": "<string>"
}
id(UUID): The tag’s unique identifier. Returned when creating viaPOST /tagsor listing viaGET /tags.name(String): Human-readable name for the tag. Must be unique per customer account. Used for matching agents to queues.detail(String): Detailed description of what this tag represents.tm_create(string, ISO 8601): Timestamp when the tag was created.tm_update(string, ISO 8601): Timestamp of the last update to any tag property.tm_delete(string, ISO 8601): Timestamp when the tag was deleted. Set to9999-01-01 00:00:00.000000if not deleted.
Note
AI Implementation Hint
Tag names must be unique within a customer account. When assigning tags to agents via PUT /agents/{id}/tag_ids, use the tag’s id (UUID), not the tag name. A tm_delete value of 9999-01-01 00:00:00.000000 is a sentinel meaning the resource has not been deleted.
Tutorial
Before working with tags, you need:
An authentication token. Obtain one via
POST /auth/loginor use an access key fromGET /accesskeys.
Note
AI Implementation Hint
Tag names must be unique within a customer account. After creating a tag, use its id (UUID) when assigning it to agents via PUT /agents/{id}/tag_ids or when configuring queue requirements via POST /queues. Tags by themselves have no effect until assigned to agents and referenced by queues.
Create a new tag
$ curl --location --request POST 'https://api.voipbin.net/v1.0/tags?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Cookie: token=<YOUR_AUTH_TOKEN>' \
--data-raw '{
"name": "test tag",
"detail": "test tag example"
}'
{
"id": "d7450dda-21e0-4611-b09a-8d771c50a5e6",
"name": "test tag",
"detail": "test tag example",
"tm_create": "2022-10-22 16:16:16.874761",
"tm_update": "9999-01-01 00:00:00.000000",
"tm_delete": "9999-01-01 00:00:00.000000"
}