Skip to content
engage-ai

Get started

Quickstart

Create an organization, load a product and a policy, check what the AI would read, and connect a Telegram bot.

This guide takes you from nothing to an AI-drafted reply. You will need curl and, for step 6, a Telegram account. It takes about ten minutes.

1. Create an organization

Signing up is the only API call that needs no credential.

curl -X POST https://api.getengageai.app/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Copper Kettle Cafe",
    "owner": { "email": "you@example.com", "name": "Your Name" }
  }'

The response holds everything you need:

{
  "organization": { "id": "…", "slug": "copper-kettle-cafe", "name": "Copper Kettle Cafe", "plan": "FREE" },
  "agentProfileId": "…",
  "login": {
    "url": "https://api.getengageai.app/auth/login",
    "email": "you@example.com",
    "password": "mFGVaAer-jKcyPp34-qxmLNojm",
    "mustChangePassword": true
  },
  "apiKey": { "prefix": "eng_live_312cf6e6", "plaintext": "eng_live_312cf6e6.fPCz…" }
}

Save the password and the API key now. They are shown once. Only hashes are stored, so they cannot be retrieved later, only replaced.

Put the key in your shell for the rest of this guide:

export ENGAGE_API_KEY="eng_live_312cf6e6.fPCz…"

Signup is limited to 5 requests a minute and 20 a day per IP address. An email that already has an account returns 409.

2. Check the key works

curl https://api.getengageai.app/auth/me -H "Authorization: Bearer $ENGAGE_API_KEY"
{ "organizationId": "…", "kind": "api_key", "scopes": ["*"], "userId": null, "mustChangePassword": null }

3. Add a product

curl -X POST https://api.getengageai.app/products \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "BOOT-TRL-9",
    "name": "Trailhead Mid GTX Boot",
    "description": "Waterproof mid-cut hiking boot with a Gore-Tex membrane. Sizes UK 4-13.",
    "priceAmount": 13500,
    "priceCurrency": "GBP",
    "stockQuantity": 30
  }'

Prices are in minor units: 13500 with GBP is £135.00. The product is indexed in the background, usually within a few seconds. To load a whole catalogue at once, see catalogue import.

4. Add a policy

curl -X POST https://api.getengageai.app/knowledge/documents \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "POLICY",
    "title": "Returns policy",
    "content": "Unworn items can be returned within 30 days of delivery for a full refund. Worn footwear cannot be returned unless faulty."
  }'

5. See what the AI would read

Before any customer writes in, ask the API what it would retrieve for a question. This is the same retrieval the reply engine runs, without generating a reply.

curl -X POST https://api.getengageai.app/knowledge/preview \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "do the trailhead boots come in a UK 11?" }'

Each result has a relevance from 0 to 1 and the excerpt the model would see. If the right fact is not in the list, the AI cannot answer with it. Fix the content, not the prompt.

6. Connect a Telegram bot

Telegram is the quickest channel to set up. In Telegram, message @BotFather, send /newbot and follow the two prompts. It replies with a token like 7654321:AAHdqTcv…. The digits before the colon are the bot id.

Make up a random secret, then connect:

curl -X POST https://api.getengageai.app/channels/connect \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerKey": "telegram_bot",
    "externalAccountId": "7654321",
    "displayName": "Copper Kettle (Telegram)",
    "credentials": {
      "botToken": "7654321:AAHdqTcv…",
      "webhookSecretToken": "a-random-string-you-chose"
    }
  }'

The response contains a webhookUrl. Tell Telegram to deliver messages there:

curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -d "url=<webhookUrl>" \
  -d "secret_token=a-random-string-you-chose"

{"ok":true,"result":true,"description":"Webhook was set"} means it worked. WhatsApp takes more steps. See Connect a channel.

7. Send a message and approve the reply

Message your bot from your own Telegram account: "Do the Trailhead boots come in a UK 11?"

New channels start in review mode, so the AI drafts a reply and waits for a person. Find the conversation:

curl https://api.getengageai.app/conversations -H "Authorization: Bearer $ENGAGE_API_KEY"

Read its messages. The draft has "status": "DRAFT". If there is no draft, the AI escalated instead and the conversation's status is AWAITING_HUMAN; How replies work explains why that happens.

curl https://api.getengageai.app/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $ENGAGE_API_KEY"

Approve it, optionally with your own wording, and it is delivered to Telegram:

curl -X POST https://api.getengageai.app/conversations/messages/$MESSAGE_ID/approve \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Next steps