Webchat

The webchat is a channel like the others: each company webchat has a channelId (see GET /webchat or GET /channels) and its conversations land in the inbox. Through the API you do two things with it:

Talk to the visitor

The company sends messages to whoever is on the webchat, with POST /messages, including interactive messages. messages module.

Be the visitor

Your system opens a session for one of your users, sends their messages and reads the team’s replies. webchat module.

Send to a visitor

A webchat visitor does not need a phone number, so the recipient is the ticketId of a conversation or the contactId of someone who has already opened this webchat:

curl --request POST \
  --url "$CONNECTA_URL/messages" \
  --header "Authorization: Bearer $CONNECTA_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-88213-notice" \
  --data '{
    "channelId": 11,
    "type": "text",
    "contactId": 842,
    "body": "Hi, Maria! Your order is out for delivery."
  }'

A contact who has never opened this webchat gets 422 ERR_API_CONTACT_UNREACHABLE. The rest of the send works like the other channels: 202 with a jobId, and the job lookup at GET /messages/jobs/{jobId}. See Send messages.

The webchat does not use templates. type: template only applies to official WhatsApp channels.

Interactive messages

The webchat shows the visitor the same interactive messages as the official WhatsApp API, with the same interactive object: the payload you already send to official WhatsApp works on the webchat with no changes. Only the channelId and the recipient change.

`type`	What the visitor sees
`button`	Up to 3 reply buttons, with an optional header (text, image, video or document) and footer.
`list`	A button that opens the list of options, organized in sections, with descriptions.
`cta_url`	A button that opens the link in a new tab.
`location_request_message`	A button that asks the browser for the location and sends it.
`carousel`	Side-by-side cards, each with an image or video, text and one link button or reply buttons.

flow, product, product_list, catalog_message, address_message, voice_call and call_permission_request depend on Meta resources and do not exist on the webchat.

{
  "channelId": 11,
  "type": "interactive",
  "contactId": 842,
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Menu" },
    "body": { "text": "What would you like to order?" },
    "footer": { "text": "Delivery within 40 min" },
    "action": {
      "button": "See menu",
      "sections": [
        {
          "title": "Burgers",
          "rows": [
            { "id": "cheeseburger", "title": "Cheeseburger", "description": "Bun, patty and cheese" },
            { "id": "salad-burger", "title": "Salad burger" }
          ]
        },
        { "title": "Drinks", "rows": [{ "id": "juice", "title": "Fresh juice" }] }
      ]
    }
  }
}

On the webchat, interactive is checked during the call itself, with the WhatsApp limits (3 buttons, 10 rows, 20- or 24-character titles and the others, listed in the interactive field of POST /messages). Outside them, the response is a 422 right away, with the field and the reason in message:

{
  "error": {
    "code": "ERR_API_INTERACTIVE_INVALID",
    "message": "interactive.action.buttons: de 1 a 3 botões"
  }
}

Header and card media only by a public http or https link. The webchat does not use media uploaded to Meta (id).

The visitor’s reply

The choice arrives as it does on WhatsApp: a text message from the visitor with the option title, replying to (quoting) the interactive message. A location arrives like a WhatsApp location, with mediaType: locationMessage. If you follow the conversation with GET /tickets/{ticketId}/messages, nothing changes compared to WhatsApp.

Chat as the visitor

With the webchat module, your system plays the visitor’s part: for example, your own app that shows the support conversation inside it.

Open the session

Use the webchat slug (from GET /webchat). With externalId, the same person always returns to the same session and the same contact.

curl --request POST \
  --url "$CONNECTA_URL/webchat/site-institucional-3f9a/sessions" \
  --header "Authorization: Bearer $CONNECTA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "user-1029",
    "visitor": { "name": "Maria Souza", "email": "maria@email.com" }
  }'

Keep the session.id. The response also includes a visitorToken, which your front end uses to receive messages in real time (/webchat, Socket.IO, auth: { token }) without exposing the API token.

Send the visitor's messages

curl --request POST \
  --url "$CONNECTA_URL/webchat/site-institucional-3f9a/sessions/$SESSION/messages" \
  --header "Authorization: Bearer $CONNECTA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "text": "Hi, I would like a quote" }'

The first message opens the ticket in the webchat queue. A file goes as multipart/form-data, in the media field.

Read the replies

Without real time, poll with after set to the createdAt of the last message received:

curl --request GET \
  --url "$CONNECTA_URL/webchat/site-institucional-3f9a/sessions/$SESSION/messages?after=2026-10-01T13:45:00.000Z" \
  --header "Authorization: Bearer $CONNECTA_TOKEN"

Mark messages as read with POST /webchat/{slug}/sessions/{sessionId}/read and close the session with POST /webchat/{slug}/sessions/{sessionId}/close.

Reply to an interactive message

In the company’s interactive messages, interactive has what to render (type, header, body, footer and the options) and options lists the reply options with id and title. To choose one, send the message id and the option id:

{ "interactiveReply": { "messageId": "6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f", "optionId": "cheeseburger" } }

The saved title comes from the message itself: there is no need, and no way, to send a different one. An option that is not in the message gets 422 ERR_WEBCHAT_INTERACTIVE_REPLY_INVALID. For a location request (interactive.type: location_request), send the coordinates, quoting the request:

{
  "location": { "latitude": -23.561399, "longitude": -46.656571 },
  "quotedMessageId": "6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f"
}

Any message can reply to another one with quotedMessageId.

Send messages

The four send types, the jobId and the job states.

Errors

The webchat and message codes.

Get started

Essentials

Guides

Talk to the visitor

Be the visitor

Send to a visitor

Interactive messages

The visitor’s reply

Chat as the visitor

Reply to an interactive message

Send messages

Errors

Talk to the visitor

Be the visitor

​Send to a visitor

​Interactive messages

​The visitor’s reply

​Chat as the visitor

​Reply to an interactive message

Send messages

Errors

Send to a visitor

Interactive messages

The visitor’s reply

Chat as the visitor

Reply to an interactive message