Get started

Quickstart

Make a sandbox key, open a conversation with Texa AI, send a message and read its reply.

This takes about five minutes. You need a Texa Desk account (sign up at texadesk.com) where you are an administrator, and a terminal.

1. Make a sandbox key

In Texa Desk, open Texa AI → Developers → API keys and choose New key:

Environment: Sandbox. A sandbox key (texa_test_…) reaches the same agent, knowledge and approved procedures as live, but nothing reaches a real customer and actions are answered by fixtures you set.
Name: something you'll recognise in the request log, such as "Laptop".

The key is shown once. Copy it into your shell:

Shell

export TEXA_API_KEY=texa_test_...

Keep keys on your server. Never put one in an app or a web page: anyone with it can act as your business. (For apps and pages there are widget sessions.)

2. Check the key

Shell

curl https://api.texadesk.com/v1/me -H "Authorization: Bearer $TEXA_API_KEY"

The answer names your account and says "environment": "test".

3. Open a conversation

curl https://api.texadesk.com/v1/conversations \
  -H "Authorization: Bearer $TEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-user-1842" \
  -d '{"channel": "web", "customer_ref": "user-1842", "first_name": "Tolu"}'

# pip install texa
from texa import Client

texa = Client()            # reads TEXA_API_KEY
convo = texa.open_conversation(channel="web", customer_ref="user-1842",
                               first_name="Tolu", idempotency_key="quickstart-user-1842")
print(convo["conversation_id"])

// npm install @texadesk/sdk
import { TexaClient } from "@texadesk/sdk";

const texa = new TexaClient({ key: process.env.TEXA_API_KEY! });
const convo = await texa.openConversation(
  { channel: "web", customer_ref: "user-1842", first_name: "Tolu" }, "quickstart-user-1842");
console.log(convo.conversation_id);

JSON

{"conversation_id": "cnv_8a7f0c...", "state": "active", "events": []}

customer_ref is your id for the customer. Texa AI remembers a customer across conversations by it, so use the same one every time.

4. Send the customer's message

curl https://api.texadesk.com/v1/conversations/cnv_8a7f0c.../messages \
  -H "Authorization: Bearer $TEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "msg-1", "text": "Hello, what are your opening hours?"}'

out = texa.send_message(convo["conversation_id"], "Hello, what are your opening hours?",
                        message_id="msg-1")
for e in out["events"]:
    if e["type"] == "reply":
        print(e["text"])

const out = await texa.sendMessage(convo.conversation_id,
  { text: "Hello, what are your opening hours?", message_id: "msg-1" });
for (const e of out.events) if (e.type === "reply") console.log(e.text);

JSON

{
  "conversation_id": "cnv_8a7f0c...",
  "state": "active",
  "events": [
    {"type": "reply", "reply_id": "rpl_...", "format": "chat",
     "text": "We're open Monday to Friday, 8:00 to 18:00, and Saturday 9:00 to 14:00."}
  ]
}

Texa AI answers from the knowledge your team approved in Texa Desk (Texa AI → Knowledge). If it has no knowledge yet, it says it doesn't know rather than making something up.

message_id is your own id for the message. Send the same one again (after a timeout, say) and you get the first answer back, marked "replayed": true: nothing runs twice.

5. Read the events

Every answer carries events, in order. Show each reply to the customer. The others tell you what else happened:

Event	What to do
`reply`	Show `text` to the customer
`action_request`	Texa AI needs something from your systems. See actions
`handover`	People take over now; Texa AI stops replying. See handing over
`close`	The conversation is over

6. Look at it in Texa Desk

Open Texa AI → Developers → Request log to see each request you made, its status and its request id. With handover to Texa Desk switched on (the default), conversations that need a person appear in your App conversations inbox.