--- title: "Agent" slug: "server-api-global-setting-agent" updated: 2022-10-27T04:00:54Z published: 2022-10-27T04:00:54Z canonical: "developer.comm100.com/server-api-global-setting-agent" --- > ## Documentation Index > Fetch the complete documentation index at: https://developer.comm100.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent ## Agent You need the Manage Agent & Agent Roles permission to manage agents. - `Agents` - Agents Manage - `GET global/agents` - [Get the list of Agents](/docs/server-api-global-setting-agent#get-the-list-of-agents) - `GET global/agents/{id}` - [Get a single Agent](/docs/server-api-global-setting-agent#get-a-single-agent) - `POST global/agents` - [Create a new Agent](/docs/server-api-global-setting-agent#create-a-new-agent) - `POST Global/agents/{id}:changePassword` - [Change the agent's password](/docs/server-api-global-setting-agent#change-the-agents-passward) - `POST Global/agents/{id}:unlock` - [Unlock the Agent](/docs/server-api-global-setting-agent#unlock-the-agent) - `PUT global/agents/{id}` - [Update the Agent](/docs/server-api-global-setting-agent#update-the-agent) - `DELETE global/agents/{id}` - [Remove the Agent](/docs/server-api-global-setting-agent#remove-the-agent) ### Agent JSON Format Agent is represented as simple flat JSON objects with the following keys: | Name | Type | Description | | --- | --- | --- | | `id` | guid | Id of the agent. | | `email` | string | Agent login email. | | `displayName` | string | Different Agents can have the same Display Name. If not display name given, will be set by both first name and last name. | | `firstName` | string | First name of the agent. | | `lastName` | string | Last name of the agent. | | `isAdmin` | bool | Whether the agent is an administrator or not. | | `isActive` | bool | Whether the agent is active or not. | | `phone` | string | Phone number of the agent. | | `title` | string | Title of the agent. | | `bio` | string | Bio info of the agent. You can pass both plaintext and base64 encoded text. If the request containing plaintext is blocked by comm100 WAF, use base64 format. When using base64, add "data:text/plain;base64," before the content. | | `timeZone` | string | Time zone of the agent. Value includes all [Time Zone Option](/server-api-introduction#time-zone-options) identifiers, if not selected, will use the time zone selected in site profile. | | `datetimeFormat` | string | Date & Time format selected by agents to display on the site. Allowed values are "YYYY/MM/DD HH:mm:ss", "YYYY-MM-DD HH:mm:ss", "MM/DD/YYYY HH:mm:ss", "MM-DD-YYYY HH:mm:ss", "DD/MM/YYYY HH:mm:ss", "DD-MM-YYYY HH:mm:ss". | | `createdTime` | datetime | Time when the agent was created. | | `isLocked` | bool | Whether the account is locked or not. | | `lockedTime` | datetime | Time when the agent account got locked. | | `ifCustomizeAvatar` | bool | Whether the agent avatar is customized or not. | | `customizeAvatar` | image | Customized avatar of agent. | | `systemAvatarId` | guid | Id of system avatar. | | `avatar` | string | Avatar of the agent. | | `permissionIds` | array | The list of permission identifiers. | | `departmentIds` | array | Id of the selected agents for this department. | | `roleIds` | array | The selected agents for this role.If not offered, will use role identifier of "AllAgents" as default. | | `skillIds` | array | The skills for the selected agents. | | `superAgentId` | guid | The super agent id When the agent is a super agent, "00000000-0000-0000-0000-000000000000" means agent is not a super agent. | | `language` | string | The control panel display language. | | `isDeleted` | bool | Whether the agent is deleted or not. | | `externalId` | string | External id of the thirdparty system. | | `shiftIds` | array | The shifts for the selected agents. | | `chatbotStartTriggerActionIds` | array | The chatbot smart trigger actions for the selected agents. | | `triggerIds` | array | The chatbot smart triggers for the selected agents. | | `segmentIds` | array | The segmentations for the selected agents. | | `isSeat` | bool | Whether agent is counted into purchased agent license number or not. | | `lastLoginTime` | datetime | The time of the last login to Comm100 account(Control Panel or Agent Console). | ### Get the list of Agents `GET global/agents` - #### Parameters: | Name | Type | in | Required | Description | | --- | --- | --- | --- | --- | | `keywords` | string | query | no | Filter by keywords in agent display name and email. | | `departmentId` | string | query | no | Id of the department. | | `roleId` | string | query | no | Id of the role. | | `include` | string | query | no | Allowed values are "department", "role", "systemAvatar", "shift", "permission","siteAgentActivity". | - #### Response: An array of [Agent](/docs/server-api-global-setting-agent#agent-json-format) - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents \ -X 'GET' \ -H 'Authorization: Bearer {access_token}' \ ``` Response: HTTP/1.1 200 OK ``` [ { "avatar": "https://api11.comm100.io/Global/agents/2e4e44a0-3910-41e7-a9b5-b7cfe8f2d52d/avatar?SiteId=70000687&version=920b345dfe5d42cf0441305e5a1191dc", "id": "2e4e44a0-3910-41e7-a9b5-b7cfe8f2d52d", "superAgentId": "00000000-0000-0000-0000-000000000000", "email": "test@2.ccc", "displayName": "test Comm100", "firstName": "test", "lastName": "Comm100", "isAdmin": true, "isActive": true, "phone": "", "title": "", "bio": "", "timeZone": "Hawaiian Standard Time", "datetimeFormat": "YYYY/MM/DD HH:mm:ss", "systemAvatarId": "2d83d4fd-3114-eb11-80fc-00155d081d0b", "ifCustomizeAvatar": false, "customizeAvatar": null, "createdTime": "2022-06-28T07:46:57.3466667Z", "isLocked": false, "lockedTime": "1900-01-01T00:00:00Z", "language": "zh-CN", "isSeat": true, "isDeleted": false, "externalId": "", "permissionIds": [ 1 ], "departmentIds": [ "b6ff11d8-0be7-4e99-b8c7-5a7ab501c69b" ], "roleIds": [ "e0bf1302-d145-eb11-8100-00155d081d0b" ], "shiftIds": [ "3db96458-9446-466a-a0b8-49d469185825", "1dfd687b-68e8-4870-95e0-68052fd08bb5", "514fdca0-df42-4f25-b919-15633e4cd59d" ], "chatbotSmartTriggerActionIds": [ "27147759-44f7-495e-a9ca-e49c5b58ca09" ], "triggerIds": [ "d84427d9-6ea6-440f-8d31-3d55d98f7aff", "dd6e6fa6-d543-4407-8d58-6694402566bb" ], "segmentIds": [ "7f8c4778-2126-4ff3-a4ba-9089cf24159c" ], "skillIds": [ "ec79aeb2-d88d-46ac-b391-9d2828992224" ] } ] ``` ### Get a single Agent `GET global/agents/{id}` - #### Parameters: | Name | Type | in | Required | Description | | --- | --- | --- | --- | --- | | `include` | string | query | no | Allowed values are "department", "role", "systemAvatar", "shift", "permission". | - #### Response: [Agent](/docs/server-api-global-setting-agent#agent-json-format) - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062 \ -X 'GET' \ -H 'Authorization: Bearer {access_token}' \ ``` Response: HTTP/1.1 200 OK ``` { "avatar": "https://api11.comm100.io/Global/agents/2e4e44a0-3910-41e7-a9b5-b7cfe8f2d52d/avatar?SiteId=70000687&version=920b345dfe5d42cf0441305e5a1191dc", "id": "2e4e44a0-3910-41e7-a9b5-b7cfe8f2d52d", "superAgentId": "00000000-0000-0000-0000-000000000000", "email": "1@2.ouath", "displayName": "aaa s211 - 212", "firstName": "aaa", "lastName": "s211212", "isAdmin": true, "isActive": true, "phone": "", "title": "", "bio": "", "timeZone": "Hawaiian Standard Time", "datetimeFormat": "YYYY/MM/DD HH:mm:ss", "systemAvatarId": "2d83d4fd-3114-eb11-80fc-00155d081d0b", "ifCustomizeAvatar": false, "customizeAvatar": null, "createdTime": "2022-06-28T07:46:57.3466667Z", "isLocked": false, "lockedTime": "1900-01-01T00:00:00Z", "language": "zh-CN", "isDeleted": false, "externalId": "", "permissionIds": [ 1 ], "departmentIds": [ "b6ff11d8-0be7-4e99-b8c7-5a7ab501c69b" ], "roleIds": [ "e0bf1302-d145-eb11-8100-00155d081d0b" ], "shiftIds": [ "3db96458-9446-466a-a0b8-49d469185825", "1dfd687b-68e8-4870-95e0-68052fd08bb5", "514fdca0-df42-4f25-b919-15633e4cd59d" ], "chatbotSmartTriggerActionIds": [ "27147759-44f7-495e-a9ca-e49c5b58ca09" ], "triggerIds": [ "d84427d9-6ea6-440f-8d31-3d55d98f7aff", "dd6e6fa6-d543-4407-8d58-6694402566bb" ], "segmentIds": [ "7f8c4778-2126-4ff3-a4ba-9089cf24159c" ], "skillIds": [ "ec79aeb2-d88d-46ac-b391-9d2828992224" ], "lastLoginTime": "2022-07-04T01:03:32.7413361Z" } ``` ### Create a new Agent `POST global/agents` - #### Parameters: | Name | Type | in | Required | Description | | --- | --- | --- | --- | --- | | `email` | string | body | yes | Agent login email. | | `password` | string | body | yes | Login password of the agent. | | `displayName` | string | body | yes | Different Agents can have the same Display Name. If not display name given, will be set by both first name and last name. | | `firstName` | string | body | yes | First name of the agent. | | `lastName` | string | body | yes | Last name of the agent. | | `isAdmin` | bool | body | no | Whether the agent is an administrator or not. | | `isActive` | bool | body | no | Whether the agent is active or not. | | `phone` | string | body | no | Phone number of the agent. | | `title` | string | body | no | Title of the agent. | | `bio` | string | body | no | Bio info of the agent. You can pass both plaintext and base64 encoded text. If the request containing plaintext is blocked by comm100 WAF, use base64 format. When using base64, add "data:text/plain;base64," before the content. | | `timeZone` | string | body | yes | Time zone of the agent. Value includes all [Time Zone Option](/server-api-introduction#time-zone-options) identifiers, if not selected, will use the time zone selected in site profile. | | `datetimeFormat` | string | body | yes | Date & Time format selected by agents to display on the site. Allowed values are "YYYY/MM/DD HH:mm:ss", "YYYY-MM-DD HH:mm:ss", "MM/DD/YYYY HH:mm:ss", "MM-DD-YYYY HH:mm:ss", "DD/MM/YYYY HH:mm:ss", "DD-MM-YYYY HH:mm:ss". | | `createdTime` | datetime | body | no | Time when the agent was created. | | `ifCustomizeAvatar` | bool | body | no | Whether the agent avatar is customized or not. | | `customizeAvatar` | image | body | no | Customized avatar of agent. | | `systemAvatarId` | guid | body | no | Id of system avatar. | | `isLocked` | bool | body | no | Whether the account is locked or not. | | `lockedTime` | datetime | body | no | Time when the agent account got locked. | | `isDeleted` | bool | body | no | Whether the agent is deleted or not. | | `language` | string | body | no | The control panel display language. | | `superAgentId` | guid | body | no | The super agent id When the agent is a super agent, "00000000-0000-0000-0000-000000000000" means agent is not a super agent. | | `externalId` | string | body | no | External id of the thirdparty system. | | `avatar` | string | body | no | Avatar of the agent. | | `permissionIds` | array | body | no | The list of permission identifiers. | | `departmentIds` | array | body | no | Id of the selected agents for this department. | | `roleIds` | array | body | no | The selected agents for this role.If not offered, will use role identifier of "AllAgents" as default. | | `shiftIds` | array | body | no | The shifts for the selected agents. | | `chatbotSmartTriggerActionIds` | array | body | no | The chatbot smart trigger actions for the selected agents. | | `triggerIds` | array | body | no | The chatbot smart triggers for the selected agents. | | `segmentIds` | array | body | no | The segmentations for the selected agents. | | `skillIds` | array | body | no | The skills for the selected agents. | - #### Response: [Agent](/docs/server-api-global-setting-agent#agent-json-format) - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents \ -X 'POST' \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ -D '{"email":"andy@comm100.com","password":"abc1234.","displayName":"Andy Liao","firstName":"Andy","lastName":"Liao","isAdmin":true,"isActive":true,"phone":"13712345678","title":"Manager","bio":"Hello, I am Andy","timeZone":"Pacific Standard Time","datetimeFormat":"YYYY/MM/DD HH:mm:ss","createdTime":"2020-12-25T06:01:00.913Z","isLocked":true,"lockedTime":"2020-12-25T06:01:00.93Z","ifCustomizeAvatar":true,"customizeAvatar":"https://dash11.comm100.io/Global/agents/c1ad60f8-e2e1-47d2-ad50-8b5de24d2b06/customizeAvatar?SiteId=10000&version=6e7b513d20baaf89b84e81e56d365111","systemAvatarId":"1383d4fd-3114-eb11-80fc-00155d081d0b"}' ``` Response: HTTP/1.1 201 Created ``` { "avatar": "https://api11.comm100.io/v4/Global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062/avatar", "id": "c2c165b7-d5ce-40e5-a492-f586f514a062", "email": "andy@comm100.com", "displayName": "Andy Liao", "firstName": "Andy", "lastName": "Liao", "isAdmin": true, "isActive": true, "phone": "13712345678", "title": "Manager", "bio": "Hello, I am Andy", "timeZone": "Pacific Standard Time", "datetimeFormat": "YYYY/MM/DD HH:mm:ss", "systemAvatarId": "1383d4fd-3114-eb11-80fc-00155d081d0b", "ifCustomizeAvatar": true, "customizeAvatar": "https://dash11.comm100.io/Global/agents/c1ad60f8-e2e1-47d2-ad50-8b5de24d2b06/customizeAvatar?SiteId=10000&version=6e7b513d20baaf89b84e81e56d365111", "createdTime": "2020-12-25T06:01:00.913Z", "isLocked": false, "lockedTime": "2020-12-25T06:01:00.93Z", "isDeleted": false, "language": "en", "superAgentId": "00000000-0000-0000-0000-000000000000", "externalId": "", "permissionIds": [ "45A2EF45-7D46-EB11-8100-00155D081D0B" ], "departmentIds": [ "b6ff11d8-0be7-4e99-b8c7-5a7ab501c69b" ], "roleIds": [ "e0bf1302-d145-eb11-8100-00155d081d0b" ], "shiftIds": [], "chatbotSmartTriggerActionIds": [], "triggerIds": [], "segmentIds": [], "skillIds": [] } ``` ### Change the agent's password `POST Global/agents/{id}:changePassword` - #### Parameters: | Name | Type | in | Required | Description | | --- | --- | --- | --- | --- | | `password` | string | body | yes | New password of the agent. | - #### Response: No Content - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents/edd568c2-9e9f-416c-b98b-17fb03c1ee52:changePassword \ -X 'POST' \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ -D '{"password":"Aa5857dksc"}' ``` Response: HTTP/1.1 200 OK ### Unlock the agent `POST Global/agents/{id}:unlock` - #### Parameters: No Parameters - #### Response: No Content - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents/edd568c2-9e9f-416c-b98b-17fb03c1ee52:unlock \ -X 'POST' \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ ``` Response: HTTP/1.1 200 OK ### Update the Agent `PUT global/agents/{id}` - #### Parameters: | Name | Type | in | Required | Description | | --- | --- | --- | --- | --- | | `email` | string | body | yes | Agent login email. | | `displayName` | string | body | yes | Different Agents can have the same Display Name. If not display name given, will be set by both first name and last name. | | `firstName` | string | body | yes | First name of the agent. | | `lastName` | string | body | yes | Last name of the agent. | | `isAdmin` | bool | body | no | Whether the agent is an administrator or not. | | `isActive` | bool | body | no | Whether the agent is active or not. | | `phone` | string | body | no | Phone number of the agent. | | `title` | string | body | no | Title of the agent. | | `bio` | string | body | no | Bio info of the agent. You can pass both plaintext and base64 encoded text. If the request containing plaintext is blocked by comm100 WAF, use base64 format. When using base64, add "data:text/plain;base64," before the content. | | `timeZone` | string | body | yes | Time zone of the agent. Value includes all [Time Zone Option](/#time-zone-options) identifiers, if not selected, will use the time zone selected in site profile. | | `datetimeFormat` | string | body | yes | Date & Time format selected by agents to display on the site. Allowed values are "YYYY/MM/DD HH:mm:ss", "YYYY-MM-DD HH:mm:ss", "MM/DD/YYYY HH:mm:ss", "MM-DD-YYYY HH:mm:ss", "DD/MM/YYYY HH:mm:ss", "DD-MM-YYYY HH:mm:ss". | | `systemAvatarId` | guid | body | no | Id of system avatar. | | `ifCustomizeAvatar` | bool | body | no | Whether the agent avatar is customized or not. | | `customizeAvatar` | image | body | no | Customized avatar of agent. | | `createdTime` | datetime | body | no | Time when the agent was created. | | `isLocked` | bool | body | no | Whether the account is locked or not. | | `lockedTime` | datetime | body | no | Time when the agent account got locked. | | `isDeleted` | bool | body | no | Whether the agent is deleted or not. | | `language` | string | body | no | The control panel display language. | | `superAgentId` | guid | body | no | The super agent id When the agent is a super agent, "00000000-0000-0000-0000-000000000000" means agent is not a super agent. | | `externalId` | string | body | no | External id of the thirdparty system. | | `avatar` | string | body | no | Avatar of the agent. | | `permissionIds` | array | body | no | The list of permission identifiers. | | `departmentIds` | array | body | no | Id of the selected agents for this department. | | `roleIds` | array | body | no | The selected agents for this role.If not offered, will use role identifier of "AllAgents" as default. | | `shiftIds` | array | body | no | The shifts for the selected agents. | | `chatbotSmartTriggerActionIds` | array | body | no | The chatbot smart trigger actions for the selected agents. | | `triggerIds` | array | body | no | The chatbot smart triggers for the selected agents. | | `segmentIds` | array | body | no | The segmentations for the selected agents. | | `skillIds` | array | body | no | The skills for the selected agents. | - #### Response: [Agent](/docs/server-api-global-setting-agent#agent-json-format) - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062 \ -X 'PUT' \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ -D '{"email":"andy@comm100.com","displayName":"Andy Liao","firstName":"Andy","lastName":"Liao","isAdmin":true,"isActive":true,"phone":"13712345678","title":"Manager","bio":"Hello, I am Andy","timeZone":"Pacific Standard Time","datetimeFormat":"YYYY/MM/DD HH:mm:ss","createdTime":"2020-12-25T06:01:00.913Z","isLocked":true,"lockedTime":"2020-12-25T06:01:00.93Z","ifCustomizeAvatar":true,"customizeAvatar":"https://dash11.comm100.io/Global/agents/c1ad60f8-e2e1-47d2-ad50-8b5de24d2b06/customizeAvatar?SiteId=10000&version=6e7b513d20baaf89b84e81e56d365111","systemAvatarId":"1383d4fd-3114-eb11-80fc-00155d081d0b"}' ``` Response: HTTP/1.1 200 OK ``` { "avatar": "https://api11.comm100.io/v4/Global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062/avatar", "id": "c2c165b7-d5ce-40e5-a492-f586f514a062", "email": "andy@comm100.com", "displayName": "Andy Liao", "firstName": "Andy", "lastName": "Liao", "isAdmin": true, "isActive": true, "phone": "13712345678", "title": "Manager", "bio": "Hello, I am Andy", "timeZone": "Pacific Standard Time", "datetimeFormat": "YYYY/MM/DD HH:mm:ss", "systemAvatarId": "1383d4fd-3114-eb11-80fc-00155d081d0b", "ifCustomizeAvatar": true, "customizeAvatar": "https://dash11.comm100.io/Global/agents/c1ad60f8-e2e1-47d2-ad50-8b5de24d2b06/customizeAvatar?SiteId=10000&version=6e7b513d20baaf89b84e81e56d365111", "createdTime": "2020-12-25T06:01:00.913Z", "isLocked": false, "lockedTime": "2020-12-25T06:01:00.93Z", "isDeleted": false, "language": "en", "superAgentId": "00000000-0000-0000-0000-000000000000", "externalId": "", "permissionIds": [ "45A2EF45-7D46-EB11-8100-00155D081D0B" ], "departmentIds": [ "b6ff11d8-0be7-4e99-b8c7-5a7ab501c69b" ], "roleIds": [ "e0bf1302-d145-eb11-8100-00155d081d0b" ], "shiftIds": [], "chatbotSmartTriggerActionIds": [], "triggerIds": [], "segmentIds": [], "skillIds": [] } ``` ### Remove the Agent `DELETE global/agents/{id}` - #### Parameters: No Parameters - #### Response: No Content - #### Example Sample Request: ``` curl https://api11.comm100.io/v4/global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062 \ -X 'DELETE' \ -H 'Authorization: Bearer {access_token}' \ ``` Response: HTTP/1.1 204 No Content