Conversation starters

The first screen of a chat decides whether people write to you. Each messaging platform has its own version of that screen: a greeting, suggested questions, a menu. Pozy manages them per account, and any of them can start a workflow when tapped.

Each endpoint supports GET to read, PUT to replace (WhatsApp uses POST) and DELETE to clear. A PUT replaces everything already set, including other locales.

#How taps reach you

A tap on a Get Started button, an ice breaker or a postback menu item sends a postback. It arrives as message.received with the tapped item's payload in metadata.postbackPayload.

Set the payload to pozy:workflow:<workflowId> and the tap starts that workflow directly. The workflow must be active on the same account and profile. On WhatsApp, a tapped prompt arrives as an ordinary message with its text, so answer it with an inbound_message workflow keyed on that text.

#Facebook welcome screen

#Greeting

curl -X PUT https://api.pozy.ai/v1/accounts/6650c1e2a3b4c5d6e7f80a55/messenger-greeting \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": [
      { "locale": "default", "text": "Hi {{user_first_name}}, ask us anything about orders and returns." },
      { "locale": "es_ES", "text": "Hola {{user_first_name}}, pregúntanos lo que quieras sobre pedidos." }
    ]
  }'

One entry must use locale default. Text is up to 160 characters. Meta fills {{user_first_name}}, {{user_last_name}} and {{user_full_name}} for each person.

#Get Started button

PUT .../messenger-get-started with a single payload (up to 1,000 characters). Meta requires a Get Started button before it shows a persistent menu on a Page, so set this first. To remove it, delete the persistent menu first: Meta refuses while a menu is set.

#Ice breakers

curl -X PUT https://api.pozy.ai/v1/accounts/6650c1e2a3b4c5d6e7f80a55/messenger-ice-breakers \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ice_breakers": [
      {
        "locale": "default",
        "call_to_actions": [
          { "question": "Where is my order?", "payload": "pozy:workflow:6650c1e2a3b4c5d6e7f80d55" },
          { "question": "How do returns work?", "payload": "RETURNS_FAQ" }
        ]
      }
    ]
  }'

Up to 4 questions per locale, each up to 80 characters, with one locale default.

#Instagram ice breakers

Instagram takes a flat list instead of locales:

{
  "ice_breakers": [
    { "question": "Do you ship to Canada?", "payload": "SHIPPING_CA" },
    { "question": "Talk to a person", "payload": "pozy:workflow:6650c1e2a3b4c5d6e7f80d56" }
  ]
}

Up to 4 entries, each question up to 80 characters.

#Persistent menu

The persistent menu uses Meta's menu format: up to 3 top-level items, up to 5 nested items.

{
  "persistent_menu": [
    {
      "locale": "default",
      "composer_input_disabled": false,
      "call_to_actions": [
        { "type": "postback", "title": "Track my order", "payload": "pozy:workflow:6650c1e2a3b4c5d6e7f80d55" },
        { "type": "web_url", "title": "Shop", "url": "https://acme.example/shop" },
        { "type": "postback", "title": "Talk to a person", "payload": "HUMAN" }
      ]
    }
  ]
}

The same endpoint serves Facebook Pages and Instagram accounts. Instagram accounts connected through Facebook Login are set through their linked Page.

#Telegram bot commands

Telegram is coming soon and cannot be connected yet. This is how its bot commands will work.

{
  "commands": [
    { "command": "start", "description": "Start over" },
    { "command": "orders", "description": "See your recent orders" },
    { "command": "help", "description": "Talk to support" }
  ]
}

Up to 100 commands. Names are lowercase letters, digits and underscores, up to 32 characters, without the leading slash. Descriptions are up to 256 characters. A command arrives as a normal message with its text, so match it with an inbound_message workflow.

#WhatsApp prompts and commands

POST /v1/whatsapp/conversational-automation sets, for one WhatsApp accountId:

Only the fields you send change. DELETE clears every prompt and command and turns the welcome message off. See WhatsApp.

#Facebook Page details

The same group of endpoints reads and updates a Page's public info: GET and PATCH /v1/accounts/{accountId}/facebook-page-info cover about (up to 100 characters), description, website, phone, emails and opening hours. Only the fields you send change; send an empty string to clear one. Editing needs a Page role that can edit the Page.

#Endpoints