Example: Fetch customer data and use it on set operations based on a condition

In these examples, we'll fetch customer data from an external RESTful web service and set a preferred / required agent, queue, or priority based on a condition applied to the data.

The examples use so-called echo integrations that are needed because you cannot run a conditional set operation on CAD that is saved in the same response.

Note:

When using the examples that connect to third-party AI services or any other third-party service, please be aware that these services are not operated by Sinch, and we do not guarantee their availability or performance. Data processed through these services is handled outside of the Sinch Contact Pro environment, so it is important to review their privacy policies and data retention practices, and to ensure your use complies with applicable laws and regulations, including GDPR. Sinch support is limited to the integration process within the Sinch Contact Pro product. Any service-specific issues should be directed to the third-party support team.

Set preferred agent in any channel

In this example, we'll fetch customer data from an external RESTful web service and set a preferred agent based on a condition applied to the data.

Note: This example works for inbound conversations in all channels.

We'll need two endpoints for this example:

Endpoint 1: For fetching customer data from an external RESTful web service based on the source address of the related conversation and saving the data as conversation attached data (CAD) of the conversation.
In this example, this kind of response is expected:
```
{
    "records": [
        {
            "id": "<record-identifier>",
            "fields": {
                "rank": "100",
                "agent": "agent@acme.com"
            }
        }
    ]
}
```
The configuration for endpoint 1:
- Endpoint URL: https://<hostname-and-resource-path-of-the-external-web-service>
- Ordinal: 1 (processed before the second endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 2
- JSON for Configuration:
```
{
    "request": {
        "params": {
            "source": "{contact.source}"
        }
    },
    "response": {
        "save": {
            "api-response-rank": "{response.body.records[-1].fields.rank}",
            "api-response-agent": "{response.body.records[-1].fields.agent}"
        }
    }
}
```
  This stores the fields.rank and fields.agent property values of the last entry in the records object array (indicated by index value -1) to CAD under keys api-response-rank and api-response-agent.
Endpoint 2: For conditionally setting a preferred agent for the conversation based on the response from the web service configured for the first endpoint.

The configuration for endpoint 2:
- Endpoint URL: edi://echo
- Ordinal: 2 (processed after the first endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 1
- JSON for Configuration:
```
{
    "request": {
        "condition": "int(contact.get_attached_data().get('api-response-rank', 0)) >= 100",
        "method": "POST",
        "body": {
            "agent": "{contact.cad.api-response-agent}"
        }
    },
    "response": {
        "set": {
            "preferredAgent": "{response.body.content.agent}"
        }
    }
}
```
  This sends the fields.agent property value (agent's chat address) in CAD under key api-response-agent, stored in the endpoint 1 configuration, and uses it from the echoed-back response content body to set the preferred agent for the related conversation. The operation is conditional and will only be executed if the fields.rank property value from the first response, saved in CAD under key api-response-rank, has a value greater than or equal to 100.

Possible results:

Preferred agent is set if a customer data record is found, a matching agent is found based on agent identifier and rank is greater than or equal to 100.
Preferred agent is not set if the web service gives an error, a customer data record is not found, no matching agent is found, or a matching agent is found but rank is less than 100.

Set preferred agent in chat channel

In this example, we'll fetch customer data from an external RESTful web service and set a preferred agent based on a condition applied to the data.

Note: This example only works for the chat channel because the condition refers to values inside the JSON object saved into CAD.

We'll need two endpoints for this example:

Endpoint 1: For fetching customer data from an external RESTful web service based on the source address of the related conversation and saving the data as conversation attached data (CAD) of the conversation.
In this example, this kind of response is expected:
```
{
    "records": [
        {
            "id": "<record-identifier>",
            "fields": {
                "rank": "100",
                "agent": "agent@acme.com"
            }
        }
    ]
}
```
The configuration for endpoint 1:
- Endpoint URL: https://<hostname-and-resource-path-of-the-external-web-service>
- Ordinal: 1 (processed before the second endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 2
- JSON for Configuration:
```
{
    "request": {
        "params": {
            "source": "{contact.source}"
        }
    },
    "response": {
        "save": {
            "api-response": "{response.body.records[-1].fields}"
        }
    }
}
```
  This stores the fields object of the last entry in the records object array (indicated by index value -1) to CAD under key api-response.
Endpoint 2: For conditionally setting a preferred agent for the conversation based on the response from the web service configured for the first endpoint.

The configuration for endpoint 2:
- Endpoint URL: edi://echo
- Ordinal: 2 (processed after the first endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 1
- JSON for Configuration:
```
{
    "request": {
        "condition": "contact.get_attached_data()['api-response']['rank'] >= 100",
        "method": "POST",
        "body": {
            "api-response": "{contact.cad.api-response}"
        }
    },
    "response": {
        "set": {
            "preferredAgent": "{response.body.content.api-response.agent}"
        }
    }
}
```
  This sends the fields object in CAD, stored in the endpoint 1 configuration, and uses its agent property value (agent's chat address) from the echoed-back response content body to set the preferred agent for the related conversation. The operation is conditional and will only be executed if the rank property value found in the stored fields object has a value greater than or equal to 100.

Possible results:

Preferred agent is set if a customer data record is found, a matching agent is found based on agent identifier, and rank is greater than or equal to 100.
Preferred agent is not set if the web service gives an error, a customer data record is not found, no matching agent is found, or a matching agent is found but rank is less than 100.

Set required agent

In this example, we'll fetch customer data from an external RESTful web service and set required agents based on a condition applied to the data.

Note: Setting required agents is only supported in chat and email channels.

Tip: For chats, you can construct the configurations in a simpler way as you can refer to values of JSON objects in CAD. For details, see Set preferred agent in chat channel.

We'll need two endpoints for this example:

Endpoint 1: For fetching customer data from an external RESTful web service based on the source address of the related conversation and saving the data as conversation attached data (CAD) of the conversation.
In this example, this kind of response is expected:
```
{
    "records": [
        {
            "id": "<record-1-identifier>",
            "fields": {                 
                "agent": "agent@acme.com"
            }
        }, {
            "id": "<record-2-identifier>",
            "fields": {                 
                "agent": "agent2@acme.com"
            }
        }
    ],
    "rank": "100"
}
```
The configuration for endpoint 1:
- Endpoint URL: https://<hostname-and-resource-path-of-the-external-web-service>
- Ordinal: 1 (processed before the second endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 2
- JSON for Configuration:
```
{
    "request": {
    "method": "GET",
        "params": {
            "source": "{contact.source}"
        }
    },
    "response": {
        "save": {
            "api-response-agent1": "{response.body.content.records[0].fields.agent}",
            "api-response-agent2": "{response.body.content.records[1].fields.agent}",
            "api-response-rank": "{response.body.content.rank}"
        }
    }
}
```
  This stores the fields.agent value of the first two entries in the records object array (indicated by index values 0 and 1) to CAD under keys api-response-agent1 and api-response-agent2, and rank from the response body under key api-response-rank.
Endpoint 2: For conditionally setting required agents for the conversation based on the response from the web service configured for the first endpoint.

The configuration for endpoint 2:
- Endpoint URL: edi://echo
- Ordinal: 2 (processed after the first endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 1
- JSON for Configuration:
```
{
    "request": {
        "condition": "int(contact.get_attached_data()['api-response-rank']) >= 100",
        "method": "POST",
        "body": {
            "agent1": "{contact.cad.api-response-agent1}",
            "agent2": "{contact.cad.api-response-agent2}"
        }
    },
    "response": {
         "set": {
            "requiredAgents": {
                "agents": [
                  "{response.body.content.agent1}",
                  "{response.body.content.agent2}"
                ],
                "timeout": "600"
           }
        }
    }
}
```
  This sends the agent1 and agent2 values in CAD, stored in the endpoint 1 configuration and uses their values (agent's chat address) from the echoed-back response content body to set the required agents for the related conversation. The operation is conditional and will only be executed if the api-response-rank property value found in CAD has a value greater than or equal to 100. The rank value is also converted into integer.

Possible results:

Required agent is set if a customer data record is found, a matching agent is found based on agent identifier, and rank is greater than or equal to 100.
Required agent is not set if the web service gives an error, a customer data record is not found, no matching agent is found, or a matching agent is found but rank is less than 100.

Set queue

In this example, we'll combine JSON configuration data with content language detection data queried from an external web service (https://rapidapi.com/detectlanguage/api/language-detection-2 ) and set the queue for an email conversation based on a condition applied to the data.

We'll need two endpoints for this example:

Endpoint 1: For querying content language detection data from the external RESTful web service based on message subject and body text of the conversation and saving the relevant part of the response as CAD of the conversation.

In this example, this kind of response is expected:
```
{
    "data": {
        "detections": [
            {
                "language": "en",
                "isReliable": true,
                "confidence": 15.75
            }
        ]
    }
}
```
The configuration for endpoint 1:
- Endpoint URL: https://community-language-detection.p.rapidapi.com/detect
- Ordinal: 1 (processed before the second endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 2
- JSON for Configuration:
```
{
    "request": {
        "method": "POST",
        "headers": {
            "x-rapidapi-key": "{authentications.api-key}",
            "x-rapidapi-host": "community-language-detection.p.rapidapi.com"
        },
        "body": {
            "q": "{contact.email.subject}\n\n{contact.email.body}"
        }
    },
    "response": {
        "save": {
            "api-response-language": "{response.body.data.detections[0].language}",
            "api-response-reliable": "{response.body.data.detections[0].isReliable}"
        }
    }
}
```
  This saves the language and isReliable property values of the first entry in the data.detections object array (indicated by index value 0) in CAD under keys api-response-language and api-response-reliable, respectively. These contain the detected primary language and the reliability of the detection result.
Endpoint 2: For conditionally setting the queue of the conversation based on response data from the web service configured for the first endpoint.

The configuration for endpoint 2:
- Endpoint URL: edi://echo
- Ordinal: 2 (processed after the first endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 1
- JSON for Configuration:
```
{
    "request": {
        "condition": "contact.get_attached_data().get('api-response-reliable') == 'true'",
        "method": "POST",
        "body": {
            "address": "service-{contact.cad.api-response.language}@acme.com"
        }
    },
    "response": {
        "set": {
            "queue": {
                "address": "{response.body.content.address}"
            }
        }
    }
}
```
  Uses the api-response-language CAD value, stored from the first response, with JSON configuration data to construct an email queue address and sends it as part of request content data. Then, uses the constructed address value from the echoed-back response content body to set the queue for the conversation as the email queue with that address. This only done if the language detection has been reliable (api-response-reliable CAD value is true).
email queues in the system with language specific addresses, such as
- service-en@acme.com
- service-fi@acme.com
- service-sv@acme.com

Possible results:

Queue is set if a language detection result is found in the response and is considered reliable.
Queue is not set if the web service gives an error, no language detection result is received, or a result is received but is not considered realiable.

Set priority

In this example, we'll fetch customer data from an external RESTful web service and set priority based on a condition applied to the data.

Note: This example works for inbound conversations from all channels.

We'll need two endpoints for this example:

Endpoint 1: For fetching customer data from an external RESTful web service based on the source address of the related conversation and saving the data as conversation attached data (CAD) of the conversation.
In this example, this kind of response is expected:
```
{
    "records": [
        {
            "id": "<record-identifier>",
            "fields": {
                "first_name": "Jane",
                "last_name": "Doe",
                "bonus_points": 1150
            }
        }
    ]
}
```
The configuration for endpoint 1:
- Endpoint URL: https://<hostname-and-resource-path-of-the-external-web-service>
- Ordinal: 1 (processed before the second endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 2
- JSON for Configuration:
```
{
    "request": {
        "params": {
            "source": "{contact.source}"
        }
    },
    "response": {
        "save": {
            "api-response-bonus-points": "{response.body.records[0].fields.bonus_points}"
        }
    }
}
```
  This stores the fields.bonus_points value of the first entry in the records object array (indicated by index value 0) to CAD under key api-response-bonus-points.
Endpoint 2: For conditionally setting the priority for the conversation based on the response from the web service configured for the first endpoint.

The configuration for endpoint 2:
- Endpoint URL: edi://echo
- Ordinal: 2 (processed after the first endpoint)
- Triggering Events: Received
- Queues: Same as for endpoint 1
- JSON for Configuration:
```
{
    "request": {
        "condition": "int(contact.get_attached_data().get('api-response-bonus-points')) >= 1000",
        "method": "POST",
        "body": {
            "priority": 50
        }
    },
    "response": {
        "set": {
            "priority": "{response.body.content.priority}"
        }
    }
}
```
  This sends a statically configured priority value (50) as part of request content data. Then, it uses the value from the echoed-back response content (body) to set the priority of the related conversation. The operation is conditional and will only be executed if the api-response-bonus-points property value found in CAD has a value greater than or equal to 1000. The rank value is also converted into integer.

Possible results:

Priority is set if a customer data record is found and its bonus points value is greater than or equal to 1000.
Priority is not set if the web service gives an error, no customer data record is found, or a customer data record is found but its bonus points value is less than 1000.