# Conversation starters

Set the greeting, Get Started button, ice breakers and persistent menu people see when they open a chat with your Facebook Page or Instagram account, plus the WhatsApp equivalent.

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](https://pozy.ai/docs/automations/workflows) when tapped.

| Surface | What people see | Platforms | Endpoint |
| --- | --- | --- | --- |
| Greeting text | A short welcome before the first message | Facebook | `/v1/accounts/{accountId}/messenger-greeting` |
| Get Started button | A button that opens the conversation | Facebook | `/v1/accounts/{accountId}/messenger-get-started` |
| Ice breakers | Up to 4 suggested questions | Facebook, Instagram | `/v1/accounts/{accountId}/messenger-ice-breakers`, `/v1/accounts/{accountId}/instagram-ice-breakers` |
| Persistent menu | A menu always available in the chat | Facebook, Instagram | `/v1/accounts/{accountId}/messenger-menu` |
| Bot commands | The `/` command menu | Telegram (coming soon) | `/v1/accounts/{accountId}/telegram-commands` |
| Prompts and commands | Suggested prompts, slash commands, welcome message | WhatsApp | `/v1/whatsapp/conversational-automation` |

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

```bash
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

```bash
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:

```json
{
  "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.

```json
{
  "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.

```json
{
  "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`:

| Field | Notes |
| --- | --- |
| `prompts` | Up to 3 suggested prompts, 80 characters each |
| `commands` | Up to 30 slash commands, each `{ command_name, command_description }` |
| `enable_welcome_message` | Turn the welcome message on or off |

Only the fields you send change. `DELETE` clears every prompt and command and turns the welcome message off. See [WhatsApp](https://pozy.ai/docs/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

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/accounts/{accountId}/facebook-page-info`](https://pozy.ai/docs/api/getFacebookPageInfo) | Get a Facebook Page's public info |
| [`PATCH /v1/accounts/{accountId}/facebook-page-info`](https://pozy.ai/docs/api/updateFacebookPageInfo) | Update a Facebook Page's public info |
| [`GET /v1/accounts/{accountId}/messenger-menu`](https://pozy.ai/docs/api/getMessengerMenu) | Get persistent menu |
| [`PUT /v1/accounts/{accountId}/messenger-menu`](https://pozy.ai/docs/api/setMessengerMenu) | Set persistent menu |
| [`DELETE /v1/accounts/{accountId}/messenger-menu`](https://pozy.ai/docs/api/deleteMessengerMenu) | Delete persistent menu |
| [`GET /v1/accounts/{accountId}/messenger-get-started`](https://pozy.ai/docs/api/getMessengerGetStarted) | Get FB Get Started button |
| [`PUT /v1/accounts/{accountId}/messenger-get-started`](https://pozy.ai/docs/api/setMessengerGetStarted) | Set FB Get Started button |
| [`DELETE /v1/accounts/{accountId}/messenger-get-started`](https://pozy.ai/docs/api/deleteMessengerGetStarted) | Delete FB Get Started button |
| [`GET /v1/accounts/{accountId}/messenger-greeting`](https://pozy.ai/docs/api/getMessengerGreeting) | Get FB greeting text |
| [`PUT /v1/accounts/{accountId}/messenger-greeting`](https://pozy.ai/docs/api/setMessengerGreeting) | Set FB greeting text |
| [`DELETE /v1/accounts/{accountId}/messenger-greeting`](https://pozy.ai/docs/api/deleteMessengerGreeting) | Delete FB greeting text |
| [`GET /v1/accounts/{accountId}/messenger-ice-breakers`](https://pozy.ai/docs/api/getMessengerIceBreakers) | Get FB ice breakers |
| [`PUT /v1/accounts/{accountId}/messenger-ice-breakers`](https://pozy.ai/docs/api/setMessengerIceBreakers) | Set FB ice breakers |
| [`DELETE /v1/accounts/{accountId}/messenger-ice-breakers`](https://pozy.ai/docs/api/deleteMessengerIceBreakers) | Delete FB ice breakers |
| [`GET /v1/accounts/{accountId}/instagram-ice-breakers`](https://pozy.ai/docs/api/getInstagramIceBreakers) | Get IG ice breakers |
| [`PUT /v1/accounts/{accountId}/instagram-ice-breakers`](https://pozy.ai/docs/api/setInstagramIceBreakers) | Set IG ice breakers |
| [`DELETE /v1/accounts/{accountId}/instagram-ice-breakers`](https://pozy.ai/docs/api/deleteInstagramIceBreakers) | Delete IG ice breakers |
| [`GET /v1/accounts/{accountId}/telegram-commands`](https://pozy.ai/docs/api/getTelegramCommands) | Get TG bot commands |
| [`PUT /v1/accounts/{accountId}/telegram-commands`](https://pozy.ai/docs/api/setTelegramCommands) | Set TG bot commands |
| [`DELETE /v1/accounts/{accountId}/telegram-commands`](https://pozy.ai/docs/api/deleteTelegramCommands) | Delete TG bot commands |

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/whatsapp/conversational-automation`](https://pozy.ai/docs/api/getWhatsAppConversationalAutomation) | Get ice breakers and commands |
| [`POST /v1/whatsapp/conversational-automation`](https://pozy.ai/docs/api/setWhatsAppConversationalAutomation) | Set ice breakers and commands |
| [`DELETE /v1/whatsapp/conversational-automation`](https://pozy.ai/docs/api/deleteWhatsAppConversationalAutomation) | Clear ice breakers and commands |