Struct¶

Agent¶

{
    "id": "<string>",
    "customer_id": "<string>",
    "username": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "ring_method": "<string>",
    "status": "<string>",
    "permission": <number>,
    "tag_ids": [
        "<string>"
    ],
    "addresses": [
        ...
    ],
    "direct_hash": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
},

id (UUID): The agent’s unique identifier. Returned when creating an agent via POST /agents or when listing agents via GET /agents.
customer_id (UUID): The customer’s ID. Obtained from the id field of GET https://api.voipbin.net/v1.0/customer.
username (String): The agent’s login username. Must be unique within the customer account.
name (String): The agent’s display name.
detail (String): An optional description of the agent.
ring_method (enum string): The method used to ring the agent’s addresses when a call is routed. See Ring method.
status (enum string): The agent’s current availability status. See Status.
permission (Integer): The agent’s permission level as a bitmask value. See Permission.
tag_ids (Array of UUID): List of tag IDs used as a skill-based filter for this agent. Each ID is obtained from the id field of GET /tags. Queue call routing considers an agent eligible only if it shares at least one tag with the queue’s own tag_ids (see Agent Overview).
addresses (Array of Object): List of contact addresses where calls are delivered to this agent. See Address.
direct_hash (String): Hash for direct agent access, already prefixed with direct. (e.g. direct.a8f3b2c1d4e5). Empty string when direct access is disabled. When enabled, this value forms the direct SIP URI directly: sip:<direct_hash>@sip.voipbin.net. Regenerate via POST /agents/{id}/direct-hash-regenerate.
tm_create (string, ISO 8601): Timestamp when the agent was created.
tm_update (string, ISO 8601): Timestamp when the agent was last updated.
tm_delete (string, ISO 8601): Timestamp when the agent was deleted, if applicable.

Note

AI Implementation Hint

A tm_delete value of 9999-01-01 00:00:00.000000 indicates the agent has not been deleted. When creating an agent, status defaults to offline and permission defaults to 0 (no permissions). The agent must set their status to available via PUT /agents/{id}/status before they can receive queue calls.

Note

AI Implementation Hint: PUT partial update

PUT /agents/{id} (admin/manager) and PUT /service_agents/me (agent self-service) both use partial-update (“omit to leave unchanged”) semantics for name, detail, and ring_method. Omit any field from the request body to leave its current stored value unchanged; only fields explicitly present in the request are modified. In particular, sending a rename-only body such as {"name": "New Name"} will NOT reset ring_method or clear detail.

Ring method¶

The method used to ring the agent’s contact addresses when a call is routed.

Type	Description
ringall	Dial all of the agent’s addresses simultaneously. The first address to answer is connected; the rest are cancelled.
linear	Dial the agent’s addresses one at a time, in order. If one address doesn’t answer, the next address is dialed.

Status¶

The agent’s current availability status. Determines whether the agent can receive calls from queues.

Type	Description
available	Agent is logged in and ready to receive queue calls.
away	Agent is temporarily unavailable (e.g., break, meeting). Cannot receive queue calls.
busy	Agent is currently handling a call. Set automatically by the system. Cannot receive additional queue calls.
offline	Agent is logged out of the system. Cannot receive queue calls.

Permission¶

The agent’s permission level, represented as a bitmask integer.

Permission	Description
0	(0x0000) No permissions.
65535	(0xFFFF) All permissions.
1	(0x0001) VoIPBin project super admin.
15	(0x000F) All project-level permissions.
16	(0x0010) Customer-level agent (basic user).
32	(0x0020) Customer-level admin (can manage agents and resources).
64	(0x0040) Customer-level manager.
240	(0x00F0) All customer-level permissions.

Push device¶

A push device of an agent: one installed app that can receive notifications. Returned by POST /service_agents/push_devices and DELETE /service_agents/push_devices/{id}.

{
    "id": "<string>",
    "customer_id": "<string>",
    "agent_id": "<string>",
    "platform": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>"
}

id (UUID): The device’s unique identifier. Returned from the POST /service_agents/push_devices response.
customer_id (UUID): The customer ID of the owner agent. Obtained from GET /service_agents/me.
agent_id (UUID): The owner agent’s ID. Obtained from GET /service_agents/me.
platform (enum string): The platform of the app. Only android is supported.
tm_create (string, ISO 8601): Timestamp when the device was first registered.
tm_update (string, ISO 8601): Timestamp when the device was last registered or refreshed.

Note

AI Implementation Hint

The push token is never part of a response. Registering the same token again keeps the id and moves tm_update.

Push settings¶

The push notification settings of an agent. Returned by GET and PUT /service_agents/me/push_settings and by PUT and DELETE /service_agents/me/push_mutes/{chat_id}.

{
    "kinds": {
        "chat_mentioned": true,
        "chat_message": false,
        "conversation_message": true,
        "case_assigned": true,
        "case_note": false
    },
    "muted_chat_ids": [
        "5d7f9b1c-3e4a-4c68-8a0e-2c4e6a8c0e11"
    ]
}

kinds (Object): Every kind the agent can switch, with true for on and false for off. The keys are chat_mentioned, chat_message, conversation_message, case_assigned and case_note.
muted_chat_ids (Array of UUID): The chats the agent muted, the oldest mute first. Each ID is a chat id returned from GET /service_agents/talk_chats. Empty when no chat is muted.