Contents x
    Trigger Experience
    • 19 Nov 2024
    • 3 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Trigger Experience

    • Updated on 19 Nov 2024
    • 3 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    The API described allows for triggering specific steps in a customer or patient journey within an Experience. It requires header parameters like an API key and path parameters including a client ID and a unique trigger ID generated by the Relay system. Clients can also create user-friendly trigger IDs. The API accepts a JSON document for body parameters, which can include optional journey IDs and asset IDs. It supports input parameters for the journey and includes properties to identify the source system making the API call. Responses include a success status with details on message delivery and notification results for each communication channel associated with the customer. Error handling is also outlined, with specific HTTP status codes for various issues, such as bad requests or unauthorized access. Overall, this API facilitates personalized customer interactions through automated journey triggers.

    Post
    /messaging/client/{client_id}/journey_trigger/{trigger_id}/customer/{ccid}

    This API can be used to trigger a specific step in an Experience for single a Customer or Patient.

    Header parameters
    xx-relay-api-key
    stringRequired

    Contains the API key needed.

    Path parameters
    client_id
    stringRequired

    Client ID

    Minimum1
    trigger_id
    stringRequired

    The unique trigger ID to be executed. Identifies the journey trigger to be launched. The Relay system generates a unique trigger_id when a user creates a journey in the CX Builder. The auto-generated trigger_id looks like (13425ae9-7ce7-4109-beeb-b0970894bbb2). Additionally, a client can create a more user friendly trigger_id, like (Delivery-Reminder-2), using the CX Builder. This API will accept either option.

    Max length100
    ccid
    stringRequired

    Identifies a unique client Customer or Patient.

    Max length100
    Body parameters

    A trigger experience JSON document

    Expand All
    object
    journey_id
    string

    If this optional property is set, the system will verify that the trigger_id is contained within the specified journey and if it is not an error will be returned.

    Max length100
    Example4d215f9f-596b-4bd4-9d19-645c87c8ea3a
    asset_id
    string

    This asset id to override in the message.

    Max length100
    Example5da610e9e-896r-3ba4-7a13-321c87c7ff6a
    client_message_tag
    string

    This is a arbitrary passthrough property specified by the Client for reporting and tracking by the Client.

    Max length100
    ExamplecampaignA
    input_parameters
    object (inputParameters)

    This property contains a collection of input properties for the Journey. Input parameters are defined when the Journey is created or updated. Each input property must be prefixed with input_.

    input_account_active
    string
    Max length100
    ExampleTrue
    input_account_funding_date
    string
    Max length100
    Example12/01/2023
    launched_by
    object (launched_by)

    This object contains two properties, lb_name and lb_source, which a Client can use to identify their source system that made this REST API call.

    lb_name
    string

    Can be used by clients to determine the specific user if the source system in lb_source is CX portal or if it was system initiated.

    Max length255
    Example[email protected]
    lb_source
    string

    Can be used by clients to determine whether the source system launching the journey was CX Portal or their own via API call.

    Max length255
    Examplecompany-system
    Responses
    200

    A response object with the message and notification results.

    Expand All
    object
    message
    object
    status
    string
    Examplesent
    result
    object

    This object contains the status of a Message being added to the Customer or Patient Feed. Valid values are (sent - A message was placed onto the Customer or Patient feed), (not-sent - A message was not placed on the Customer or Patient Feed), (error - An error occurred while trying to place a message onto the Customer or Patient Feed)

    id
    string
    Example7e5189d2-3124-4d0f-9a7b-a894dbf74f5a
    notification
    object

    This object contains the status of sending the notification to each channel associated with the Customer or Patient. There will be one result entry for each channel associated with the Customer or Patient. For example, if the Customer or Patient has two phone numbers associated with the CCID, then there will be two result entries, one for each phone number.

    results
    Array of object (results)
    object

    This object contains the status of sending the notification to each channel associated with the Customer or Patient. There will be one result entry for each channel associated with the Customer or Patient. For example, if the Customer or Patient has two phone numbers associated with the CCID, then there will be two result entries, one for each phone number.

    channel_addr
    string

    The notification.results.channel_addr field contains the result of attempting to send a notification on the specific channel.

    Example12158372698
    channel_type
    string

    The notification.results.channel_type identifies the type of channel. Valid values are (sms - The channel_addr is a mobile phone number and the notification will be sent via SMS).

    Examplesms
    status
    string

    The notification.results.status field contains the result of attempting to send a notification on the specific channel. Valid values are (ok - A notification was successfully sent), (error-sms - An error occurred while attempting to send and SMS notification), (no-consent - The mobile number does not have consent to send a notification), (channel-deactivated - The channel has been deactivated and can no longer received notifications).

    Exampleok
    id
    string
    Exampleef4a71f9-3bcb-4bd2-83eb-83e051ce15a5
    status
    string

    This field is being deprecated and should no longer be used. Use the notification.results.status property instead.

    Examplesent
    schedule
    string
    Exampleempty
    400

    Bad Request. If there is an error with the request POST body, the HTTP status code will be set to 400 and the response body will contain specific details on the error. Note that the structure of the error response JSON may differ depending on the nature of the error.

    Expand All
    object
    error
    object
    ccid
    string
    Examplerelay-customer
    type
    string
    Examplemissing-fields
    data
    Array of object
    object

    A array of unique trigger_id and ccid combinations to which to send Relay experiences.

    Exampleinput_customer_name1
    401

    Unauthorized

    404

    Not Found - The requested resource was not found. Please verify the route parameter.

    409

    Conflict - Indicates the request could not be processed. A common reason is when attempting to create a new Journey object, but the ID already exists in the system.

    500

    An unexpected server error occurred. The response body should contain additional information related to the server error. Please retry your request.

    Was this article helpful?
    What's Next