Skip to main content

Access Zoe via API token

Use an API token to connect your application to a Zoe Advisor and start making requests.

Get your API token​

  • Go to Advisor Studio.
  • Open a published Zoe Advisor.
  • Navigate to Integrations > API token.
  • Copy the API token shown on the screen.

Use this token in your application to authorize access to the Zoe API.

API Integration

Make a request​

Use the token to send a POST request to the /message endpoint. Include a user message and a few parameters in the body.

Example request:

POST https://orca-advisor-api.zoovu.com/api/v2/runtime/zoe/YOUR_API_TOKEN/message?locale="en-IE"
Content-Type: application/json

To track user interactions and store conversation history, include the following identifiers in your request:

  • sessionId – required to save Zoe's conversation history. If you don't provide it, it will be generated automatically.
  • visitId – identifies a unique browsing session (stored in the user's cookies).
  • clientId – identifies a unique user across visits (also stored in cookies).
{
  "sessionId": "00000000-aaaa-bbbb-cccc-111111111111",
  "visitId": "22222222-dddd-eeee-ffff-333333333333",
  "clientId": "00000000-aaaa-bbbb-cccc-111111111111",
  "context": {
    "isPirate": true,
    "isGamer": false
  },
  "message": {
    "actor": "user",
    "type": "question",
    "parameters": {
      "input": "I'm looking for a laptop with long battery life"
    }
  }
}

Receive a response​

Zoe returns product suggestions, follow-up questions, or a text message based on the user input.

Example response:

{
  "responses": [
    {
      "type": "text",
      "content": "Here are some laptops known for their long battery life..."
    }
  ]
}

Your application can now display these results in your own UI.

Go to Zoe API documentation.