Ultimo API

The Ultimo API builds your agents into your own product: an intranet chat, a ticket system, a CRM workflow or your own app sends messages and gets the agent's answers, keeps your knowledge in sync and receives webhooks. It is a REST API with JSON and server-to-server keys.

1 min read Updated

What you can do

The API is part of the Ultimo plan, per agent. Keys, permissions and access are explained in Authentication and keys; paging, errors, retries and limits in Conventions.

Your first request

  1. Create an integration

    In the portal, open the agents overview, click API in the sidebar, then + Integration. Give it a name, keep Chat only and copy the key. Never put the key into a website or app: it is for your server only.

  2. Find your agent id

    curl

    curl https://api.ultimo-bots.com/v1/agents -H "Authorization: Bearer $ULTIMO_API_KEY"
  3. Send a message

    curl https://api.ultimo-bots.com/v1/responses \
      -H "Authorization: Bearer $ULTIMO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "agent_id": "YOUR_AGENT_ID",
        "input": "When are you open on Saturday?",
        "external_id": "ticket-4711",
        "end_user": {"id": "u-17", "name": "Anna"}
      }'

The answer:

JSON

{
  "id": "resp_6tZ0wq8Hn2cB3kQx1mJ4rV7y",
  "object": "response",
  "status": "completed",
  "agent_id": "YOUR_AGENT_ID",
  "conversation_id": "conv_9fK2pX7aQ1mL3sT8vW0yZ4bC",
  "external_id": "ticket-4711",
  "output": {"text": "On Saturday we are open from 9 am to 2 pm.", "format": "markdown", "language": "en"},
  "handoff": {"requested": false, "status": null},
  "input_message_id": "msg_0000000000081234",
  "output_message_id": "msg_0000000000081235",
  "end_user": {"id": "u-17", "name": "Anna"},
  "metadata": {},
  "usage": {"credits": 1},
  "error": null
}

Send the next message with the same external_id and the agent continues the conversation. Streams, async answers and conversations step by step: Send messages. Every field of the request and the answer: Responses reference.

Next steps