Contact usRequest a demo

The outbound request mechanism (ORM)

When the Collaboration Server needs input from an external system, it uses webhooks and the endpoints of the Unblu web API:

  1. Unblu sends the external system a webhook.

  2. The external system does whatever’s necessary to react appropriately to the webhook. This might involve calling other systems that Unblu is unaware of.

  3. Once it’s ready, the external system calls the appropriate endpoint of the Unblu web API. To do so, the external system must prepare the outcome of the webhook in such a way that the web API endpoint can process the data.

The combination of webhooks and web API calls is a robust way for systems to interact, but it does have a number of drawbacks for certain use cases:

  • Both the webhook and the call to the web API endpoint are HTTP POST requests that result in the recipient sending an HTTP response. Most of the time, this is a 200 response with no meaningful content. Furthermore, POST requests in environments with tight security measures in place can lead to high latency.

  • There’s no built-in connection between a webhook call Unblu sends and the external system’s call to a web API endpoint. This makes it harder to track which request a response refers to. In a cluster deployment, the request and response may be handled by different Collaboration Server pods.

  • Because the webhook and the web API call are two separate actions, there’s no way to ensure that there isn’t too great a delay between the two. This makes it more difficult to create low-latency interactions that need a response within a limited timeframe.

Chat suggestions are a case where the drawbacks of using two separate mechanisms become apparent.

  • Unblu must be able to determine which request a suggestion belongs to quickly. This means that both Unblu and the external system that generates chat suggestions must keep track of requests for chat suggestions.

  • An agent who requests a suggestion in a conversation can’t wait forever; the external system must respond in a timely manner. As a result, Unblu must keep track of how much time has passed since it sent a request for a chat suggestion so that it can react if the external system doesn’t respond quickly enough.

To deal with these issues, Unblu introduced a different mechanism for chat suggestions, the outbound request mechanism (ORM).

How the ORM works: an example

Like normal webhooks, the ORM uses an HTTP POST request to trigger an action in an external system, and the external system should respond with an HTTP 200 response code. Unlike normal webhooks, however, Unblu expects the HTTP response to an ORM request to contain a meaningful body.

To understand how the ORM works in more detail, consider a feature that uses it: chat suggestions.

When Unblu asks a suggestion source for a chat suggestion, the body of the HTTP POST request it sends contains a ChatSuggestionRequest, as described in the outbound.conversation.chat_suggestion webhook. (The contents of the ChatSuggestionRequest aren’t of interest in this context.)

The suggestion source processes the request and sends a 200 HTTP response. The body of the response must contain one of two types of ChatSuggestionResponse:

Note that the HTTP response code must be 200 even if the suggestion source is unable to supply a chat suggestion.

You define how long the Collaboration Server should wait for a response from the suggestion source when you create the suggestion source:

Event detection

You can use a single endpoint for multiple outbound requests. The custom HTTP header x-unblu-service-name identifies the webhook used for the outbound request. This information lets you determine the content of the HTTP request body, or to forward the request to the system that should ultimately process it.

Delivery

Unlike webhooks, which Unblu always sends to the endpoint of a single webhook registration in the order they were processed, outbound requests are delivered in parallel. The order of requests is only guaranteed with respect to the individual context. This removes a potential performance bottleneck.

For example, for any particular conversation, the outbound request for an onboarding offer is always sent before the request to open the dialog. Unblu can, however, send multiple onboarding offers in parallel for different conversations.

If a particular conversation causes problems, the other conversations are still processed.

See also