users

Creates, updates, deletes, gets or lists a users resource.

Overview

Name	users
Type	Resource
Id	aws.connect.users

Fields

The following fields are returned by SELECT queries:

describe_user

Name	Datatype	Description
after_contact_work_configs	array	A list of after contact work (ACW) timeout configuration settings for each channel.
arn	string	The Amazon Resource Name (ARN) of the user account.
auto_accept_configs	array	A list of auto-accept configuration settings for each channel.
directory_user_id	string	The identifier of the user account in the directory used for identity management.
hierarchy_group_id	string	The identifier of the hierarchy group for the user.
id	string	The identifier of the user account.
identity_info	object	Contains information about the identity of a user. For Connect Customer instances that are created with the EXISTING_DIRECTORY identity management type, FirstName, LastName, and Email cannot be updated from within Connect Customer because they are managed by the directory. The FirstName and LastName length constraints below apply only to instances using SAML for identity management. If you are using Connect Customer for identity management, the length constraints are 1-255 for FirstName, and 1-256 for LastName.
last_modified_region	string	The Amazon Web Services Region where this resource was last modified. (pattern: <code>[a-z]{2}(-[a-z]+){1,2}(-[0-9])?</code>)
last_modified_time	string (date-time)	The timestamp when this resource was last modified.
persistent_connection_configs	array	The list of persistent connection configuration settings for each channel.
phone_config	object	Contains information about the phone configuration settings for a user.
phone_number_configs	array	The list of phone number configuration settings for each channel.
routing_profile_id	string	The identifier of the routing profile for the user.
security_profile_ids	array	The identifiers of the security profiles for the user.
tags	object	The tags.
username	string	The user name assigned to the user account.
voice_enhancement_configs	array	The list of voice enhancement configuration settings for each channel.

list_users

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) of the user account.
id	string	The identifier of the user account.
last_modified_region	string	The Amazon Web Services Region where this resource was last modified. (pattern: <code>[a-z]{2}(-[a-z]+){1,2}(-[0-9])?</code>)
last_modified_time	string (date-time)	The timestamp when this resource was last modified.
username	string	The Connect Customer user name of the user account.

search_users

Name	Datatype	Description
after_contact_work_configs	array	A list of after contact work (ACW) timeout configuration settings for each channel.
arn	string	The Amazon Resource Name (ARN) of the user.
auto_accept_configs	array	A list of auto-accept configuration settings for each channel.
directory_user_id	string	The directory identifier of the user.
hierarchy_group_id	string	The identifier of the user's hierarchy group.
id	string	The identifier of the user's summary.
identity_info	object	The user's first name and last name.
persistent_connection_configs	array	The list of persistent connection configuration settings for each channel.
phone_config	object	Contains information about the phone configuration settings for a user.
phone_number_configs	array	The list of phone number configuration settings for each channel.
routing_profile_id	string	The identifier of the user's routing profile.
security_profile_ids	array	The identifiers of the user's security profiles.
tags	object	The tags used to organize, track, or control access for this resource. For example, { "Tags": {"key1":"value1", "key2":"value2"} }.
username	string	The name of the user.
voice_enhancement_configs	array	The list of voice enhancement configuration settings for each channel.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_user	select	user_id, instance_id, region		Describes the specified user. You can find the instance ID in the Connect Customer console (it’s the final part of the ARN). The console does not display the user IDs. Instead, list the users and note the IDs provided in the output.
list_users	select	instance_id, region	nextToken, maxResults	Provides summary information about the users for the specified Connect Customer instance.
search_users	select	region		Searches users in an Connect Customer instance, with optional filtering. AfterContactWorkTimeLimit is returned in milliseconds.
create_user	insert	instance_id, region, SecurityProfileIds, RoutingProfileId		Creates a user account for the specified Connect Customer instance. Certain UserIdentityInfo parameters are required in some situations. For example, Email, FirstName and LastName are required if you are using Connect Customer or SAML for identity management. Fields in PhoneConfig cannot be set simultaneously with their corresponding channel-specific configuration parameters. Specifically: PhoneConfig.AutoAccept conflicts with AutoAcceptConfigs PhoneConfig.AfterContactWorkTimeLimit conflicts with AfterContactWorkConfigs PhoneConfig.PhoneType and PhoneConfig.PhoneNumber conflict with PhoneNumberConfigs PhoneConfig.PersistentConnection conflicts with PersistentConnectionConfigs We recommend using channel-specific parameters such as AutoAcceptConfigs, AfterContactWorkConfigs, PhoneNumberConfigs, PersistentConnectionConfigs, and VoiceEnhancementConfigs for per-channel configuration. For information about how to create users using the Connect Customer admin website, see Add Users in the Connect Customer Administrator Guide.
associate_contact_with_user	update	instance_id, contact_id, region, UserId		Associates a queued contact with an agent. Use cases Following are common uses cases for this API: Programmatically assign queued contacts to available users. Leverage the IAM context key connect:PreferredUserArn to restrict contact association to specific preferred user. Important things to know Use this API with chat, email, task, and voice contacts. For voice callbacks, this API does not support customer-first mode. This API can be used to offer a contact to an agent even if the agent is currently at maximum concurrency for the channel. Use it to associate contacts with users regardless of their current state, including custom states. Ensure your application logic accounts for user availability before making associations. It honors the IAM context key connect:PreferredUserArn to prevent unauthorized contact associations. It respects the IAM context key connect:PreferredUserArn to enforce authorization controls and prevent unauthorized contact associations. Verify that your IAM policies are properly configured to support your intended use cases. The service quota Queues per routing profile per instance applies to manually assigned queues, too. For more information about this quota, see Connect Customer quotas in the Connect Customer Administrator Guide. Endpoints: See Connect Customer endpoints and quotas.
update_user_identity_info	update	user_id, instance_id, region, IdentityInfo		Updates the identity information for the specified user. We strongly recommend limiting who has the ability to invoke UpdateUserIdentityInfo. Someone with that ability can change the login credentials of other users by changing their email address. This poses a security risk to your organization. They can change the email address of a user to the attacker's email address, and then reset the password through email. For more information, see Best Practices for Security Profiles in the Connect Customer Administrator Guide.
update_user_phone_config	update	user_id, instance_id, region, PhoneConfig		Updates the phone configuration settings for the specified user. We recommend using the UpdateUserConfig API, which supports additional functionality that is not available in the UpdateUserPhoneConfig API, such as voice enhancement settings and per-channel configuration for auto-accept and After Contact Work (ACW) timeouts. In comparison, the UpdateUserPhoneConfig API will always set the same ACW timeouts to all channels the user handles.
update_user_config	update	user_id, instance_id, region		Updates the configuration settings for the specified user, including per-channel auto-accept and after contact work (ACW) timeout settings. This operation replaces the UpdateUserPhoneConfig API. While UpdateUserPhoneConfig applies the same ACW timeout to all channels, UpdateUserConfig allows you to set different auto-accept and ACW timeout values for each channel type.
put_user_status	replace	user_id, instance_id, region, AgentStatusId		Changes the current status of a user or agent in Connect Customer. If the agent is currently handling a contact, this sets the agent's next status. For more information, see Agent status and Set your next status in the Connect Customer Administrator Guide.
delete_user	delete	instance_id, user_id, region		Deletes a user account from the specified Connect Customer instance. For information about what happens to a user's data when their account is deleted, see Delete Users from Your Connect Customer Instance in the Connect Customer Administrator Guide. After calling DeleteUser, call DeleteQuickConnect to delete any records related to the deleted users. This will help you: Avoid dangling resources that impact your service quotas. Remove deleted users so they don't appear to agents as transfer options. Avoid the disruption of other Connect Customer processes, such as instance replication and syncing if you're using Connect Customer Global Resiliency.
update_user_hierarchy	exec	user_id, instance_id, region		Assigns the specified hierarchy group to the specified user.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
contact_id	string	The identifier of the contact in this instance of Connect Customer.
instance_id	string	The identifier of the Connect Customer instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
region	string	AWS region (default: us-east-1)
user_id	string	The identifier of the user account.
maxResults	integer	The maximum number of results to return per page. The default MaxResult size is 100.
nextToken	string	The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

SELECT examples

describe_user

Describes the specified user. You can find the instance ID in the Connect Customer console (it’s the final part of the ARN). The console does not display the user IDs. Instead, list the users and note the IDs provided in the output.

SELECT
after_contact_work_configs,
arn,
auto_accept_configs,
directory_user_id,
hierarchy_group_id,
id,
identity_info,
last_modified_region,
last_modified_time,
persistent_connection_configs,
phone_config,
phone_number_configs,
routing_profile_id,
security_profile_ids,
tags,
username,
voice_enhancement_configs
FROM aws.connect.users
WHERE user_id = '{{ user_id }}' -- required
AND instance_id = '{{ instance_id }}' -- required
AND region = '{{ region }}' -- required
;

list_users

Provides summary information about the users for the specified Connect Customer instance.

SELECT
arn,
id,
last_modified_region,
last_modified_time,
username
FROM aws.connect.users
WHERE instance_id = '{{ instance_id }}' -- required
AND region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

search_users

Searches users in an Connect Customer instance, with optional filtering. AfterContactWorkTimeLimit is returned in milliseconds.

SELECT
after_contact_work_configs,
arn,
auto_accept_configs,
directory_user_id,
hierarchy_group_id,
id,
identity_info,
persistent_connection_configs,
phone_config,
phone_number_configs,
routing_profile_id,
security_profile_ids,
tags,
username,
voice_enhancement_configs
FROM aws.connect.users
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_user

Creates a user account for the specified Connect Customer instance. Certain UserIdentityInfo parameters are required in some situations. For example, Email, FirstName and LastName are required if you are using Connect Customer or SAML for identity management. Fields in PhoneConfig cannot be set simultaneously with their corresponding channel-specific configuration parameters. Specifically: PhoneConfig.AutoAccept conflicts with AutoAcceptConfigs PhoneConfig.AfterContactWorkTimeLimit conflicts with AfterContactWorkConfigs PhoneConfig.PhoneType and PhoneConfig.PhoneNumber conflict with PhoneNumberConfigs PhoneConfig.PersistentConnection conflicts with PersistentConnectionConfigs We recommend using channel-specific parameters such as AutoAcceptConfigs, AfterContactWorkConfigs, PhoneNumberConfigs, PersistentConnectionConfigs, and VoiceEnhancementConfigs for per-channel configuration. For information about how to create users using the Connect Customer admin website, see Add Users in the Connect Customer Administrator Guide.

INSERT INTO aws.connect.users (
Username,
Password,
IdentityInfo,
PhoneConfig,
DirectoryUserId,
SecurityProfileIds,
RoutingProfileId,
HierarchyGroupId,
AutoAcceptConfigs,
AfterContactWorkConfigs,
PhoneNumberConfigs,
PersistentConnectionConfigs,
VoiceEnhancementConfigs,
Tags,
instance_id,
region
)
SELECT 
'{{ Username }}',
'{{ Password }}',
'{{ IdentityInfo }}',
'{{ PhoneConfig }}',
'{{ DirectoryUserId }}',
'{{ SecurityProfileIds }}' /* required */,
'{{ RoutingProfileId }}' /* required */,
'{{ HierarchyGroupId }}',
'{{ AutoAcceptConfigs }}',
'{{ AfterContactWorkConfigs }}',
'{{ PhoneNumberConfigs }}',
'{{ PersistentConnectionConfigs }}',
'{{ VoiceEnhancementConfigs }}',
'{{ Tags }}',
'{{ instance_id }}',
'{{ region }}'
RETURNING
user_arn,
user_id
;

Manifest

# Description fields are for documentation purposes
- name: users
props:
  - name: instance_id
    value: "{{ instance_id }}"
    description: Required parameter for the users resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the users resource.
  - name: Username
    value: "{{ Username }}"
  - name: Password
    value: "{{ Password }}"
  - name: IdentityInfo
    description: |
      Contains information about the identity of a user. For Connect Customer instances that are created with the EXISTING_DIRECTORY identity management type, FirstName, LastName, and Email cannot be updated from within Connect Customer because they are managed by the directory. The FirstName and LastName length constraints below apply only to instances using SAML for identity management. If you are using Connect Customer for identity management, the length constraints are 1-255 for FirstName, and 1-256 for LastName.
    value:
      FirstName: "{{ FirstName }}"
      LastName: "{{ LastName }}"
      Email: "{{ Email }}"
      SecondaryEmail: "{{ SecondaryEmail }}"
      Mobile: "{{ Mobile }}"
  - name: PhoneConfig
    description: |
      Contains information about the phone configuration settings for a user.
    value:
      PhoneType: "{{ PhoneType }}"
      AutoAccept: {{ AutoAccept }}
      AfterContactWorkTimeLimit: {{ AfterContactWorkTimeLimit }}
      DeskPhoneNumber: "{{ DeskPhoneNumber }}"
      PersistentConnection: {{ PersistentConnection }}
  - name: DirectoryUserId
    value: "{{ DirectoryUserId }}"
  - name: SecurityProfileIds
    value:
      - "{{ SecurityProfileIds }}"
  - name: RoutingProfileId
    value: "{{ RoutingProfileId }}"
  - name: HierarchyGroupId
    value: "{{ HierarchyGroupId }}"
  - name: AutoAcceptConfigs
    description: |
      A list of auto-accept configuration settings for each channel.
    value:
      - Channel: "{{ Channel }}"
        AutoAccept: {{ AutoAccept }}
        AgentFirstCallbackAutoAccept: {{ AgentFirstCallbackAutoAccept }}
  - name: AfterContactWorkConfigs
    description: |
      A list of after contact work (ACW) timeout configuration settings for each channel.
    value:
      - Channel: "{{ Channel }}"
        AfterContactWorkConfig:
          AfterContactWorkTimeLimit: {{ AfterContactWorkTimeLimit }}
        AgentFirstCallbackAfterContactWorkConfig:
          AfterContactWorkTimeLimit: {{ AfterContactWorkTimeLimit }}
  - name: PhoneNumberConfigs
    description: |
      The list of phone number configuration settings for each channel.
    value:
      - Channel: "{{ Channel }}"
        PhoneType: "{{ PhoneType }}"
        PhoneNumber: "{{ PhoneNumber }}"
  - name: PersistentConnectionConfigs
    description: |
      The list of persistent connection configuration settings for each channel.
    value:
      - Channel: "{{ Channel }}"
        PersistentConnection: {{ PersistentConnection }}
  - name: VoiceEnhancementConfigs
    description: |
      The list of voice enhancement configuration settings for each channel.
    value:
      - Channel: "{{ Channel }}"
        VoiceEnhancementMode: "{{ VoiceEnhancementMode }}"
  - name: Tags
    value: "{{ Tags }}"

UPDATE examples

associate_contact_with_user

Associates a queued contact with an agent. Use cases Following are common uses cases for this API: Programmatically assign queued contacts to available users. Leverage the IAM context key connect:PreferredUserArn to restrict contact association to specific preferred user. Important things to know Use this API with chat, email, task, and voice contacts. For voice callbacks, this API does not support customer-first mode. This API can be used to offer a contact to an agent even if the agent is currently at maximum concurrency for the channel. Use it to associate contacts with users regardless of their current state, including custom states. Ensure your application logic accounts for user availability before making associations. It honors the IAM context key connect:PreferredUserArn to prevent unauthorized contact associations. It respects the IAM context key connect:PreferredUserArn to enforce authorization controls and prevent unauthorized contact associations. Verify that your IAM policies are properly configured to support your intended use cases. The service quota Queues per routing profile per instance applies to manually assigned queues, too. For more information about this quota, see Connect Customer quotas in the Connect Customer Administrator Guide. Endpoints: See Connect Customer endpoints and quotas.

UPDATE aws.connect.users
SET 
UserId = '{{ UserId }}'
WHERE 
instance_id = '{{ instance_id }}' --required
AND contact_id = '{{ contact_id }}' --required
AND region = '{{ region }}' --required
AND UserId = '{{ UserId }}' --required;

update_user_identity_info

Updates the identity information for the specified user. We strongly recommend limiting who has the ability to invoke UpdateUserIdentityInfo. Someone with that ability can change the login credentials of other users by changing their email address. This poses a security risk to your organization. They can change the email address of a user to the attacker's email address, and then reset the password through email. For more information, see Best Practices for Security Profiles in the Connect Customer Administrator Guide.

UPDATE aws.connect.users
SET 
IdentityInfo = '{{ IdentityInfo }}'
WHERE 
user_id = '{{ user_id }}' --required
AND instance_id = '{{ instance_id }}' --required
AND region = '{{ region }}' --required
AND IdentityInfo = '{{ IdentityInfo }}' --required;

update_user_phone_config

Updates the phone configuration settings for the specified user. We recommend using the UpdateUserConfig API, which supports additional functionality that is not available in the UpdateUserPhoneConfig API, such as voice enhancement settings and per-channel configuration for auto-accept and After Contact Work (ACW) timeouts. In comparison, the UpdateUserPhoneConfig API will always set the same ACW timeouts to all channels the user handles.

UPDATE aws.connect.users
SET 
PhoneConfig = '{{ PhoneConfig }}'
WHERE 
user_id = '{{ user_id }}' --required
AND instance_id = '{{ instance_id }}' --required
AND region = '{{ region }}' --required
AND PhoneConfig = '{{ PhoneConfig }}' --required;

update_user_config

Updates the configuration settings for the specified user, including per-channel auto-accept and after contact work (ACW) timeout settings. This operation replaces the UpdateUserPhoneConfig API. While UpdateUserPhoneConfig applies the same ACW timeout to all channels, UpdateUserConfig allows you to set different auto-accept and ACW timeout values for each channel type.

UPDATE aws.connect.users
SET 
AutoAcceptConfigs = '{{ AutoAcceptConfigs }}',
AfterContactWorkConfigs = '{{ AfterContactWorkConfigs }}',
PhoneNumberConfigs = '{{ PhoneNumberConfigs }}',
PersistentConnectionConfigs = '{{ PersistentConnectionConfigs }}',
VoiceEnhancementConfigs = '{{ VoiceEnhancementConfigs }}'
WHERE 
user_id = '{{ user_id }}' --required
AND instance_id = '{{ instance_id }}' --required
AND region = '{{ region }}' --required;

REPLACE examples

put_user_status

Changes the current status of a user or agent in Connect Customer. If the agent is currently handling a contact, this sets the agent's next status. For more information, see Agent status and Set your next status in the Connect Customer Administrator Guide.

REPLACE aws.connect.users
SET 
AgentStatusId = '{{ AgentStatusId }}'
WHERE 
user_id = '{{ user_id }}' --required
AND instance_id = '{{ instance_id }}' --required
AND region = '{{ region }}' --required
AND AgentStatusId = '{{ AgentStatusId }}' --required;

DELETE examples

delete_user

Deletes a user account from the specified Connect Customer instance. For information about what happens to a user's data when their account is deleted, see Delete Users from Your Connect Customer Instance in the Connect Customer Administrator Guide. After calling DeleteUser, call DeleteQuickConnect to delete any records related to the deleted users. This will help you: Avoid dangling resources that impact your service quotas. Remove deleted users so they don't appear to agents as transfer options. Avoid the disruption of other Connect Customer processes, such as instance replication and syncing if you're using Connect Customer Global Resiliency.

DELETE FROM aws.connect.users
WHERE instance_id = '{{ instance_id }}' --required
AND user_id = '{{ user_id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

update_user_hierarchy

Assigns the specified hierarchy group to the specified user.

EXEC aws.connect.users.update_user_hierarchy 
@user_id='{{ user_id }}' --required, 
@instance_id='{{ instance_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"HierarchyGroupId": "{{ HierarchyGroupId }}"
}'
;