SSMContacts / Client / start_engagement

start_engagement

SSMContacts.Client.start_engagement(**kwargs)

Starts an engagement to a contact or escalation plan. The engagement engages each contact specified in the incident.

See also: AWS API Documentation

Request Syntax

response = client.start_engagement(
    ContactId='string',
    Sender='string',
    Subject='string',
    Content='string',
    PublicSubject='string',
    PublicContent='string',
    IncidentId='string',
    IdempotencyToken='string'
)

Parameters:

• ContactId (string) –

  [REQUIRED]

  The Amazon Resource Name (ARN) of the contact being engaged.

• Sender (string) –

  [REQUIRED]

  The user that started the engagement.

• Subject (string) –

  [REQUIRED]

  The secure subject of the message that was sent to the contact. Use this field for engagements to VOICE or EMAIL.

• Content (string) –

  [REQUIRED]

  The secure content of the message that was sent to the contact. Use this field for engagements to VOICE or EMAIL.

• PublicSubject (string) – The insecure subject of the message that was sent to the contact. Use this field for engagements to SMS.

• PublicContent (string) – The insecure content of the message that was sent to the contact. Use this field for engagements to SMS.

• IncidentId (string) – The ARN of the incident that the engagement is part of.

• IdempotencyToken (string) –

  A token ensuring that the operation is called only once with the specified details.

  This field is autopopulated if not provided.

Return type:

dict

Returns:

Response Syntax

{
    'EngagementArn': 'string'
}

Response Structure

• (dict) –

  • EngagementArn (string) –

    The ARN of the engagement.

Exceptions

• SSMContacts.Client.exceptions.AccessDeniedException

• SSMContacts.Client.exceptions.DataEncryptionException

• SSMContacts.Client.exceptions.InternalServerException

• SSMContacts.Client.exceptions.ResourceNotFoundException

• SSMContacts.Client.exceptions.ThrottlingException

• SSMContacts.Client.exceptions.ValidationException

Examples

The following start-engagement pages contact’s contact channels. Sender, subject, public-subject, and public-content are all free from fields. Incident Manager sends the subject and content to the provided VOICE or EMAIL contact channels. Incident Manager sends the public-subject and public-content to the provided SMS contact channels. Sender is used to track who started the engagement.

response = client.start_engagement(
    ContactId='arn:aws:ssm-contacts:us-east-2:111122223333:contact/akuam',
    Content='Testing engagements',
    PublicContent='Testing engagements',
    PublicSubject='test',
    Sender='tester',
    Subject='test',
)

print(response)

Expected Output:

{
    'EngagementArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:engagement/akuam/607ced0e-e8fa-4ea7-8958-a237b8803f8f',
    'ResponseMetadata': {
        '...': '...',
    },
}

The following start-engagement engages contact’s through an escalation plan. Each contact is paged according to their engagement plan.

response = client.start_engagement(
    ContactId='arn:aws:ssm-contacts:us-east-2:111122223333:contact/example_escalation',
    Content='Testing engagements',
    PublicContent='Testing engagements',
    PublicSubject='test',
    Sender='tester',
    Subject='test',
)

print(response)

Expected Output:

{
    'EngagementArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:engagement/example_escalation/69e40ce1-8dbb-4d57-8962-5fbe7fc53356',
    'ResponseMetadata': {
        '...': '...',
    },
}