Agent
  • 05 Jul 2022
  • 8 Minutes to read
  • Dark
    Light

Agent

  • Dark
    Light

Article summary

You need the Manage Site permission to manage agents.

Agent JSON Format

Agent is represented as simple flat JSON objects with the following keys:

NameTypeDescription
idguidId of the agent.
externalIdstringExternal Id of the agent.
emailstringAgent login email.
languagestringAgent language.
displayNamestringDifferent Agents can have the same Display Name. If the display name is not set, it uses the combination of first name and last name.
firstNamestringFirst name of the agent.
lastNamestringLast name of the agent.
isAdminboolWhether the agent is an administrator or not.
isActiveboolWhether the agent is active or not.
phonestringPhone number of the agent.
titlestringTitle of the agent.
biostringBio info of the agent. You can pass both plain text and base64-encoded text. If the request containing plain-text is blocked by comm100 WAF, use base64 format. When using base64, add "data:text/plain;base64," before the content.
timeZonestringTime zone of the agent. The values include all Time Zone Option identifiers. The time zone of the agent uses the time zone of the site if not configured.
datetimeFormatstringDate & 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".
createdTimedatetimeTime when the agent was created.
isLockedboolWhether the account is locked or not.
lockedTimedatetimeTime when the agent account got locked.
ifCustomizeAvatarboolWhether the agent avatar is customized or not.
customizeAvatarimageCustomized avatar of agent.
systemAvatarIdguidId of system avatar.
avatarstringAvatar of the agent.
languagestringThe language of agent.
superAgentIdguidThe super agent id When the agent is a super agent, "00000000-0000-0000-0000-000000000000" means agent is not a super agent.
permissionIdsarrayThe list of permission identifiers.
departmentIdsarrayIDs of the departments where the agent belongs to.
roleIdsarrayIDs of the roles that the agent have.
isDeletedboolWhether the agent is deleted or not.
isSeatboolWhether agent is counted into purchased agent license number or not.
shiftIdsarrayThe shifts for the selected agents.
chatbotSmartTriggerActionIdsarrayThe chatbot smart trigger actions for the selected agents.
triggerIdsarrayThe chatbot smart triggers for the selected agents.
segmentIdsarrayThe segmentations for the selected agents.
skillIdsarrayThe skills for the selected agents.
lastLoginTimedatetimeThe time of the last login to Comm100 account(Control Panel or Agent Console).

Get site Agents

GET global/agents

  • Parameters:

NameTypeinRequiredDescription
siteIdintegerqueryyesId of the site.
keywordsstringquerynoFilter by keywords in agent display name and email.
externalIdstringquerynoExternal Id of the Agent.
departmentIdstringquerynoId of the department.
roleIdstringquerynoId of the role.
includestringquerynoAllowed values are "department", "role", "systemAvatar", "shift", "permission","siteAgentActivity".
  • Response:

An array of Agent

  • Example

Sample Request:

curl https://partnerapi.comm100.io/v4/global/sites/100/agents?include=siteAgentActivity 
    -X 'GET' \ 
    -H 'Authorization: Bearer {access_token}' \ 

Response:

HTTP/1.1 200 OK

[
  {
      "id": "c2c165b7-d5ce-40e5-a492-f586f514a062",
      "externalId":"DA2E1FF1-A151-4FFE-9701-C1C8F234C632",
      "email": "andy@comm100.com",
      "displayName": "Andy Liao",
      "firstName": "Andy",
      "lastName": "Liao",
      "isAdmin": true,
      "language": "en",
      "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",
      "siteAgentActivity": {
            "siteAgentId": "e308d6ff-fb4f-4b5c-93ff-f415cd45eebf",
            "siteId": 100000064,
            "lastLoginTime": "2022-07-04T08:15:03.7024205Z",
            "isDeleted": false
      },
      "isDeleted": false,
      "language": "en",
      "superAgentId": "00000000-0000-0000-0000-000000000000",
      "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",
      "avatar": "https://api11.comm100.io/v4/Global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062/avatar",
      "permissionIds": [
          "45A2EF45-7D46-EB11-8100-00155D081D0B"
      ],
      "departmentIds": [
          "b6ff11d8-0be7-4e99-b8c7-5a7ab501c69b"
      ],
      "roleIds": [
          "e0bf1302-d145-eb11-8100-00155d081d0b"
      ],
      "shiftIds": [],
      "chatbotSmartTriggerActionIds": [],
      "triggerIds": [],
      "segmentIds": [],
      "skillIds": [],
      "lastLoginTime": "2022-07-04T08:15:03.7024205Z",
      "isSeat": true
  }
] 

Get a single Agent

GET global/agents/{id}

  • Parameters:

NameTypeinRequiredDescription
siteIdintegerqueryyesId of the site.
includestringquerynoAllowed values are "department", "role", "systemAvatar", "shift", "permission".
  • Response:

Agent

  • Example

Sample Request:

curl https://partnerapi.comm100.io/v4/global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062?siteId=100 \ 
    -X 'GET' \ 
    -H 'Authorization: Bearer {access_token}' \ 

Response:

HTTP/1.1 200 OK

{
  "id": "c2c165b7-d5ce-40e5-a492-f586f514a062",
  "externalId":"DA2E1FF1-A151-4FFE-9701-C1C8F234C632",
  "email": "andy@comm100.com",
  "displayName": "Andy Liao",
  "firstName": "Andy",
  "lastName": "Liao",
  "isAdmin": true,
  "isActive": true,
  "phone": "13712345678",
  "language": "en",
  "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",
  "avatar": "https://api11.comm100.io/v4/Global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062/avatar",
  "isDeleted": false,
  "language": "en",
  "superAgentId": "00000000-0000-0000-0000-000000000000",
  "permissionIds": [
      "45A2EF45-7D46-EB11-8100-00155D081D0B"
  ],
  "departmentIds": [
      "b6ff11d8-0be7-4e99-b8c7-5a7ab501c69b"
  ],
  "roleIds": [
      "e0bf1302-d145-eb11-8100-00155d081d0b"
  ],
  "shiftIds": [],
  "chatbotSmartTriggerActionIds": [],
  "triggerIds": [],
  "segmentIds": [],
  "skillIds": [],
  "lastLoginTime": "2022-07-04T08:15:03.7024205Z"
} 

Create a new Agent

POST global/agents

  • Parameters:

NameTypeinRequiredDescription
siteIdintegerqueryyesId of the site.
externalIdstringbodynoExternal Id of the Agent.
languagestringbodyyesAgent language.
emailstringbodyyesAgent login email.
passwordstringbodyyesLogin password of the agent.
displayNamestringbodyyesDifferent Agents can have the same Display Name. If the display name is not set, it uses the combination of first name and last name.
firstNamestringbodyyesFirst name of the agent.
lastNamestringbodyyesLast name of the agent.
isAdminboolbodynoWhether the agent is an administrator or not.
isActiveboolbodynoWhether the agent is active or not.
phonestringbodynoPhone number of the agent.
titlestringbodynoTitle of the agent.
biostringbodynoBio 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.
timeZonestringbodyyesTime zone of the agent. The values include all Time Zone Option identifiers. The time zone of the agent uses the time zone of the site if not configured.
datetimeFormatstringbodyyesDate & 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".
createdTimedatetimebodynoTime when the agent was created.
isLockedboolbodynoWhether the account is locked or not.
lockedTimedatetimebodynoTime when the agent account got locked.
ifCustomizeAvatarboolbodynoWhether the agent avatar is customized or not.
customizeAvatarimagebodynoCustomized avatar of the agent.
systemAvatarIdguidbodynoID of system avatar.
avatarstringbodynoAvatar of the agent.
permissionIdsarraybodynoThe list of permission identifiers.
departmentIdsarraybodynoIDs of the departments where the agent belongs to.
roleIdsarraybodynoIDs of the roles that the agent have.
skillIdsarraybodynoThe skills for the selected agents.
isDeletedboolbodynoWhether the agent is deleted or not.
  • Response:

Agent

  • Example

Sample Request:

curl https://partnerapi.comm100.io/v4/global/agents?siteId=100 \ 
    -X 'POST' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \ 
    -D '{"email":"test1@comm100.com", "language":"en", "password":"111111.", "displayName":"Andyiao","firstName":"test","lastName":"comm","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":"2022-12-25T06:01:00.913Z","ifCustomizeAvatar":false,"customizeAvatar":"","systemAvatarId":""}' 

Response:

HTTP/1.1 201 Created

{
  "id": "1d43482b-2362-4ac5-9fe4-c8bc0fee49b3",
  "avatar": "https://api11.comm100.io/Global/agents/1d43482b-2362-4ac5-9fe4-c8bc0fee49b3/avatar?SiteId=100&version=920b345dfe5d42cf0441305e5a1191dc",
  "ifCustomizeAvatar": false,
  "systemAvatarId": "2d83d4fd-3114-eb11-80fc-00155d081d0b",
  "displayName": "Andyiao",
  "firstName": "test",
  "lastName": "comm",
  "phone": "13712345678",
  "title": "Manager",
  "bio": "Hello, I am Andy",
  "timeZone": "Pacific Standard Time",
  "datetimeFormat": "YYYY/MM/DD HH:mm:ss",
  "isAdmin": true,
  "isActive": true,
  "email": "test1@comm100.com",
  "createdTime": "2022-07-05T02:40:15.54Z",
  "isLocked": false,
  "isDeleted": false,
  "lockedTime": "1900-01-01T00:00:00Z",
  "departmentIds": [],
  "roleIds": [
      "0ccf849a-6bfb-ec11-a83c-00155de0e608",
      "0dcf849a-6bfb-ec11-a83c-00155de0e608"
  ],
  "skillIds": [],
  "permissionIds": [],
  "language": "en",
  "externalId": ""
}

Update the Agent

PUT global/agents/{id}

  • Parameters:

NameTypeinRequiredDescription
siteIdintegerqueryyesId of the site.
emailstringbodyyesAgent login email.
languagestringbodyyesAgent language.
displayNamestringbodyyesDifferent Agents can have the same Display Name. If the display name is not set, it uses the combination of first name and last name.
firstNamestringbodyyesFirst name of the agent.
lastNamestringbodyyesLast name of the agent.
isAdminboolbodynoWhether the agent is an administrator or not.
isActiveboolbodynoWhether the agent is active or not.
phonestringbodynoPhone number of the agent.
titlestringbodynoTitle of the agent.
biostringbodynoBio info of the agent. You can pass both plain text and base64-encoded text. If the request containing plain text is blocked by comm100 WAF, use base64 format. When using base64, add "data:text/plain;base64," before the content.
timeZonestringbodyyesTime zone of the agent. The values include all Time Zone Option identifiers. The time zone of the agent uses the time zone of the site if not configured.
datetimeFormatstringbodyyesDate & 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".
createdTimedatetimebodynoTime when the agent was created.
isLockedboolbodynoWhether the account is locked or not.
lockedTimedatetimebodynoTime when the agent account got locked.
ifCustomizeAvatarboolbodynoWhether the agent avatar is customized or not.
customizeAvatarimagebodynoCustomized avatar of agent.
systemAvatarIdguidbodynoId of system avatar.
avatarstringbodynoAvatar of the agent.
permissionIdsarraybodynoThe list of permission identifiers.
departmentIdsarraybodynoIDs of the departments where the agent belongs to.
roleIdsarraybodynoIDs of the roles that the agent have.
skillIdsarraybodynoThe skills for the selected agents.
isDeletedboolbodynoWhether the agent is deleted or not.
externalIdstringbodynoExternal Id of the Agent.
  • Response:

Agent

  • Example

Sample Request:

curl https://partnerapi.comm100.io/v4/global/agents/1d43482b-2362-4ac5-9fe4-c8bc0fee49b3?siteId=100 \ 
    -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":false,"customizeAvatar":""}' 

Response:

HTTP/1.1 200 OK

{
  "id": "1d43482b-2362-4ac5-9fe4-c8bc0fee49b3",
  "avatar": "https://api11.comm100.io/Global/agents/97bee629-a4c9-4b27-a820-9d0a266a02e0/avatar?SiteId=100&version=920b345dfe5d42cf0441305e5a1191dc",
  "ifCustomizeAvatar": false,
  "systemAvatarId": "2d83d4fd-3114-eb11-80fc-00155d081d0b",
  "displayName": "Andy Liao",
  "firstName": "Andy",
  "lastName": "Liao",
  "phone": "13712345678",
  "title": "Manager",
  "bio": "Hello, I am Andy",
  "timeZone": "Pacific Standard Time",
  "datetimeFormat": "YYYY/MM/DD HH:mm:ss",
  "isAdmin": true,
  "isActive": true,
  "email": "andy@comm100.com",
  "createdTime": "2020-12-25T06:01:00.9133333Z",
  "isLocked": true,
  "isDeleted": false,
  "lockedTime": "2020-12-25T06:01:00.93Z",
  "departmentIds": [],
  "roleIds": [
      "bba26135-b7f6-ec11-ab81-0633ca200461",
      "bca26135-b7f6-ec11-ab81-0633ca200461"
  ],
  "skillIds": [],
  "permissionIds": [],
  "language": "en",
  "externalId": ""
}

Remove the Agent

DELETE global/agents/{id}

  • Parameters:

NameTypeinRequiredDescription
siteIdintegerqueryyesId of the site.
  • Response:

No Content

  • Example

Sample Request:

curl https://partnerapi.comm100.io/v4/global/agents/c2c165b7-d5ce-40e5-a492-f586f514a062?siteId=100 \ 
    -X 'DELETE' \ 
    -H 'Authorization: Bearer {access_token}' \ 

Response:

HTTP/1.1 204 No Content


Was this article helpful?

What's Next