Oracle Digital Assistant

Welcome to the Oracle Digital Assitant documentation for Dimension! Integrating Dimension into your Yellow AI application is quick and easy.

Obtain Oracle API Credentials

To generate an API key for the Oracle Digital Assistant:

Log into Oracle Cloud: Access your Oracle Cloud account at Oracle Cloud & Navigate to your specific Oracle Digital Assistant instance where you intend to use the API.

Open Service Console: In the Digital Assistant instance dashboard, click on the "Service Console". Once Inside the console, go to the ‘Development’ section and select ‘API Keys’.

Generate New API Key: Click on ‘Generate API Key’. You might need to enter a description for the key. Once the key is generated, it will be displayed. Ensure to copy and securely store the API key as it will not be shown again.

Use API Key for Authentication: Use this API key in your API requests to authenticate. Typically, this key will be included in the Authorization header as a Bearer token.

This process allows you to securely generate and retrieve an API key for accessing Oracle Digital Assistant's APIs, which you can then use to authenticate requests as you integrate with external systems like Dimension.

For more detailed instructions, check the Oracle documentation on sending API requests.

Set Up Authentication in Code

import requests

api_key = 'your_oracle_api_key'
headers = {'Authorization': f'Bearer {api_key}'}

Retrieve Conversations from Oracle Digital Assistant

Set up the API Request:

Use a GET method to request messages from Oracle. For instance, the API URL might look like this: https://example.oraclecloud.com/api/v1/messages.
Include an Authorization header with your API key: 'Authorization': 'Bearer {your_oracle_api_key}'.

Execute the Request:

Send the request to Oracle using a tool like Postman or a Python script.

Example Python script:

import requests
oracle_url = 'https://example.oraclecloud.com/api/v1/messages'
headers = {'Authorization': 'Bearer {your_oracle_api_key}'}
response = requests.get(oracle_url, headers=headers)
messages = response.json()

Handle the Response:

The response will likely be a JSON object containing an array of message entries.

Example of a successful response:

{
  "items": [
    {
      "id": 123,
      "text": "Hello, how can I assist you today?",
      "timestamp": "2020-01-01T00:00:00Z",
      "senderId": "agent1",
      "conversationId": "conv1"
    },
    {
      "id": 124,
      "text": "I need help with my account.",
      "timestamp": "2020-01-01T00:01:00Z",
      "senderId": "user123",
      "conversationId": "conv1"
    }
  ]
}

Each message includes details such as id, text, timestamp, senderId, and conversationId.

POST responses to Dimension

When your bot receives a message, post the data to the following endpoint:

https://tracker.dimensionlabs.io/track?platform=universal&v=10.1.1-rest&type=incoming&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

You must send the data with the following fields:

text – string – (required)
userId – string – (required) – should be the SAME userId for both incoming and outgoing messages this is NOT the bot’s user ID

To review all optional fields see our API reference.

The data to POST should pass the following data:

{
  "text": "Hi, bot",
  "userId": "+14155551234",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"text":"Hi, bot","userId":"+14155551234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"}}'
     'https://tracker.dimensionlabs.io/track?platform=sms&v=11.1.0-rest&type=incoming&apiKey=API_KEY'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.