Basics

Integrations are a powerful way to customize oratio to your workflow or to your needs to make customer communication even more efficient. You can build internal integrations just for you and your team or publish it to our marketplace to make it available for everyone on the oratio platform.

We differentiate between to kind of integrations:

  • Active integrations let you control the conversation and answer to user's messages
  • Passive integrations forward all incoming messages to your integration without interfering the workflow

Here are a few examples what you can do with integrations:

  • Automate the workflow by answering user's messages directly from your integration
  • Push all messages to your reporting or analytics tool
  • Integrate with your CRM

Active Integration

Active Integrations let you control the conversation flow. All incoming messages will be send to your webhook where you either respond with a message to the user, forward it to another integration or the oratio platform. If an Active Integration responds with a message, it's not forwarded to other Active Integrations. Admins of a team can choose in what order to add integrations to their accounts.

Passive Integration

Passive Integrations allow you to integrate with existing tools or services and forward messages without responding to them. This can be used to forward messages to your CRM, analytics or reporting tools. The difference from Active Integrations is, that every message will be send to passive integrations, even if the response is handled by another integration. No response is expected, therefore all responses from Passive Integrations will be ignored.

Design Principles

oratio API is designed according to REST design principles.

The API accepts JSON in request bodies and requires that the content-type: application/json header will be specified for all such requests. Depending on context, resources may be send as single objects or as arrays of objects, nested within the response object.

Status codes

Status Code Meaning Description
20x OK/Created/Accepted The client's request was successfully received, understood, and accepted.
400 Bad Request The request could not be understood by the server due to malformed syntaxf.
401 Unauthorized The request requires user authentication. Credentials necessary for the authorization are missing or invalid.
404 Not Found The requested resource is not found.
50x Server Error There is some problem on our end

In addition to the status code, the HTTP body of the response will also contain a JSON representation of the error.

Authorization

Create Account

Before starting to build integrations you need to create an oratio account.
Create oratio Account

If you already have an oratio account there's no need to register for oratio again.
You are good to go!

Webhooks

A webhook is a way for your app to receive real-time information whenever there are updates. It delivers data to your application as it happens, meaning you get updates immediately. This prevents you from having to rely on continuous or even periodic API requests just to check for updates that may or may not have happened. This makes webhooks much more efficient for both provider and consumer.


How does the webhook work?

You are asked to provide this URL when creating a new integration. This means that you also need to set up a URL in your app that’s accessible from the public web. The webhook will POST data to you as JSON payload.


Setting up the Webhook

After setting up your oratio account, visit the Dashboard and go to Configure > Integrations. Click on "Custom Integration" and fill out the name and enter your Webhook URL. You can also choose between an Active Integration and a Passive Integration.

You are now ready to go 🙌

Tips

Run Integrations on a Local Machine

We recommend ngrok to make your local development environment reachable from the web.

Step 1: Download ngrok and install it.

Step 2: After installation and registration start the service by entering:
ngrok http

Step 3: Copy the URL and set it as your webhook in your integration.

This URL will redirect all it's traffic to your local machine.