Use the chat API

The chat API lets your own server talk to your agent, for customers who reach you somewhere other than your website, such as your app. Your server creates a chat for a customer, sends their messages and reads the agent's replies. The agent answers from the same knowledge as on your website, and can pass the chat to your team.

Before you startCopy Anchor Link

You need two things from the agent in Turbo Agent. Both need the agent to be published.

Call the API only from your server, and keep the chat key there, such as in an environment variable. Never put it in your website or app: anyone with it can chat as your customers.

Create a chat and ask a questionCopy Anchor Link

Three requests: create a chat, send the customer's message, then list the chat's messages. Each example reads three environment variables: TURBO_ORIGIN, set to https://turboagent.app, CHANNEL_KEY, your channel address, and TURBO_API_KEY, your chat key.

# 1. Create a chat
CREATE_KEY=$(uuidgen)
CHAT_JSON=$(curl --fail-with-body -sS \
  "$TURBO_ORIGIN/v1/channels/$CHANNEL_KEY/chats" \
  -H "Authorization: Bearer $TURBO_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CREATE_KEY" -d '{"userId":"shopper_123","locale":"en"}')
CHAT_ID=$(printf '%s' "$CHAT_JSON" | jq -er '.item.id')

# 2. Send the customer's message
MESSAGE_KEY=$(uuidgen)
curl --fail-with-body -sS \
  "$TURBO_ORIGIN/v1/channels/$CHANNEL_KEY/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TURBO_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $MESSAGE_KEY" -d '{"text":"When are you open?"}'

# 3. List the chat's messages
curl --fail-with-body -sS \
  "$TURBO_ORIGIN/v1/channels/$CHANNEL_KEY/chats/$CHAT_ID/messages?limit=20" \
  -H "Authorization: Bearer $TURBO_API_KEY"

userId is your own ID for the customer. It's optional and isn't a sign-in: anyone with the chat key can use any userId.

While a chat is with your team, reply is null. List the messages to see your team's replies as they come in. The API reference has every field, with examples.

Send a request again safelyCopy Anchor Link

Every request that changes something needs an Idempotency-Key header: 8 to 128 letters, digits or . _ : -. Use a new UUID for each new request.

If you don't get an answer, such as after a timeout, send the same request again with the same key. You get the first request's result, and nothing happens twice: the customer's message is sent once and the agent answers once. So keep each key until you get an answer.

• The same key with a different request is refused with idempotency_conflict. Use a new key for a new request.
• A key that created a chat is kept for 30 days. Don't send the same create request again after that: the key may have been forgotten, so it could start a second chat. Keys for everything else are kept as long as the chat.

Stream the replyCopy Anchor Link

To show the agent's reply as it's written, add Accept: text/event-stream to a Send a message request. In cURL, with CHAT_ID from the first example:

MESSAGE_KEY=$(uuidgen)
curl --fail-with-body -sS -N \
  "$TURBO_ORIGIN/v1/channels/$CHANNEL_KEY/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TURBO_API_KEY" -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' -H "Idempotency-Key: $MESSAGE_KEY" \
  -d '{"text":"Are you open on Saturdays?"}'

You get a start event, a delta event with each new part of the reply's text, then done with the same JSON as without streaming. Streaming has the details.

Send a fileCopy Anchor Link

To send a customer's photo or document, upload it to the chat, then send its ID in the message's fileIds. Files can be JPEG, PNG, GIF, WebP, PDF or plain text, up to 4 MiB each.

# 1. Upload the file
UPLOAD_KEY=$(uuidgen)
FILE_JSON=$(curl --fail-with-body -sS \
  "$TURBO_ORIGIN/v1/channels/$CHANNEL_KEY/chats/$CHAT_ID/files" \
  -H "Authorization: Bearer $TURBO_API_KEY" -H "Idempotency-Key: $UPLOAD_KEY" \
  -F 'file=@photo.jpg')
FILE_ID=$(printf '%s' "$FILE_JSON" | jq -er '.item.id')

# 2. Send it with the customer's message
MESSAGE_KEY=$(uuidgen)
curl --fail-with-body -sS \
  "$TURBO_ORIGIN/v1/channels/$CHANNEL_KEY/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TURBO_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $MESSAGE_KEY" \
  -d "$(jq -nc --arg id "$FILE_ID" \
    '{text: "Here is a photo of the problem", fileIds: [$id]}')"

Forms and passing to your teamCopy Anchor Link

When the agent offers to pass the chat to your team, its message has a handoffOffer. To accept, send the offer's confirmationId with Pass the chat to your team. If the offer's requiresEmail is true, send the customer's email too.

If your team needs details from the customer first, such as their email, the request to accept fails with collection_incomplete and opens a form in the chat. Read its fields with Get the collection. Send the customer's answers with Submit the collection, then accept the offer again with a new Idempotency-Key.

The agent can also ask for details itself: its message then includes a collection with the form, answered the same way.

ErrorsCopy Anchor Link

Errors are JSON, with a code to act on:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again shortly.",
    "requestId": "rq_3f1c9a7e5b2d4c6a",
    "retryAfterSeconds": 2
  }
}

• 429 or 503: wait for the seconds in the Retry-After header, then send the same request with the same key.
• 500: send the same request again with the same key.
• 409 operation_interrupted: the result is unknown. List the messages before sending anything new.
• Anything else: Errors says what to do for each code.

If you ask us about a request, quote its requestId.