--- name: "chat_reply" area: "chat" title: "Reply in a chat" price: "free" method: "POST" url: "https://api.conecto.chat/v1/tools/chat_reply" mcp_server: "https://api.conecto.chat/mcp/chat" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/chat/chat_reply" --- # Reply in a chat (`chat_reply`) Answers a website visitor as the business, with product cards, images or buttons if you like. Answer the visitor as the business. A closed conversation reopens. A visitor who left gets the reply by email if they gave one. internal: true adds a private note instead of a reply. blocks adds rich content (cards with a picture, title, price and link; images; buttons). In Beside, point highlights things on the visitor's screen one after another (ids from page.elements in the chat.message_received event), and open_page takes them to another page of the site; one of the two per reply. The visitor sees the reply labelled as an AI agent's unless by_person says a person wrote it. Price: Free. A call that fails costs nothing. ## Use it when A visitor wrote in the website chat and should get an answer, or a private note belongs on the conversation. Visitors see the reply labelled as an AI agent's; pass by_person when a person at the business wrote it. - For a reply to a support ticket, use [ticket_reply](https://conecto.chat/tools/helpdesk/ticket_reply.md). - For an email to someone outside a chat, use [email_send](https://conecto.chat/tools/email/email_send.md). ## Say this to your agent > The visitor asking about the Tabor wants to know if it ships to Seattle. Tell her yes, free, in 3 to 5 days, and show her the bike. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `conversation_id` | integer | yes | At least 1. | | | | `text` | string | yes | 1 to 5,000 characters. | | | | `internal` | boolean | no | | | `false` | | `by_person` | boolean | no | true when a person at the business wrote this reply. Otherwise the visitor sees it labelled as an AI agent's (EU AI Act Art. 50). A person's reply also stops a webhook brain from answering this chat. | | `false` | | `blocks` | array of objects | no | Like [{"type": "cards", "items": [{"title": "Tabor gravel bike", "price": "$1,890", "image": "https://...", "url": "https://..."}]}]. Up to 10 items. | | | | `point` | array of objects | no | 1 to 5 items. | | | | `point[].id` | string | yes, in each item of `point` | 1 to 8 characters. | | | | `point[].say` | string | no | Up to 90 characters. | | | | `open_page` | object | no | | | | | `open_page.url` | string | yes, when `open_page` is given | Up to 600 characters. | | | | `open_page.label` | string | no | Up to 40 characters. | | | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `chat_reply` on the MCP server `https://api.conecto.chat/mcp/chat` with these arguments: ```json { "conversation_id": 3187, "text": "Yes, the Tabor ships to Seattle for free. It arrives in 3 to 5 days, tuned and ready to ride.", "blocks": [ { "type": "cards", "items": [ { "title": "Tabor gravel bike, 54 cm", "price": "$1,890", "image": "https://halversoncycle.example/img/tabor-gravel.jpg", "url": "https://halversoncycle.example/bikes/tabor" } ] } ] } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/chat_reply \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"conversation_id": 3187, "text": "Yes, the Tabor ships to Seattle for free. It arrives in 3 to 5 days, tuned and ready to ride.", "blocks": [{"type": "cards", "items": [{"title": "Tabor gravel bike, 54 cm", "price": "$1,890", "image": "https://halversoncycle.example/img/tabor-gravel.jpg", "url": "https://halversoncycle.example/bikes/tabor"}]}]}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "chat_reply", "status": "succeeded", "replayed": false, "cost_usd": "$0.00", "balance_usd": "$19.75", "result": { "sent": true, "delivered": "chat", "message_at": "2026-10-14T08:00:00+00:00", "conversation": { "conversation_id": 3187, "status": "open", "channel": "web", "visitor": { "name": "Lisa Moreno", "email": "lisa.moreno@example.com" }, "started_at": "2026-10-14T08:00:00+00:00", "last_message_at": "2026-10-14T08:00:00+00:00", "charge": "charged" } } } ``` `result`: sent: true, whether the reply was delivered (in the chat, or by email to a visitor who left), when it was sent, and the conversation. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No chat conversation of the business has that conversation_id. | Find it with chat_list_conversations and use its conversation_id. | | `invalid_input` | 400 | A block is not valid, point and open_page came together, open_page leads off the site, or point names an element that is not on the visitor's page. | Fix what the message names. Use element ids from page.elements in the latest chat.message_received event, and one of point or open_page per reply. | | `not_beside` | 409 | point or open_page was sent, but this chat runs the classic widget. | Reply with text and blocks only, or switch the widget to Beside with chat_setup. | | `conversation_closed` | 409 | The visitor has a newer open conversation. | Reply in that conversation; the message gives its id. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [chat_setup](https://conecto.chat/tools/chat/chat_setup.md): Creates or changes the business's website chat widget and who answers it, and returns the snippet for the website. $0.001 a call. - [chat_get_setup](https://conecto.chat/tools/chat/chat_get_setup.md): The website chat's settings, its embed snippet, how messages reach the agent and this month's cost. Free up to 1,000,000 reads a month. - [chat_wait](https://conecto.chat/tools/chat/chat_wait.md): Waits for the next visitor message, for an agent without a server to receive webhooks. Free up to 1,000,000 reads a month. - [chat_list_conversations](https://conecto.chat/tools/chat/chat_list_conversations.md): The website chat and email conversations, newest activity first, with who it is and the last message. Free up to 1,000,000 reads a month. - [chat_get_conversation](https://conecto.chat/tools/chat/chat_get_conversation.md): One conversation with all its messages, from the visitor and from the business. Free up to 1,000,000 reads a month. - [chat_typing](https://conecto.chat/tools/chat/chat_typing.md): Shows the visitor that the business is typing, for about 8 seconds. Free. - [chat_create_ticket](https://conecto.chat/tools/chat/chat_create_ticket.md): Opens a help desk ticket from a chat that needs follow-up by email, with the chat so far as the request. $0.01 a call. - [chat_close](https://conecto.chat/tools/chat/chat_close.md): Closes a conversation once it is handled, or opens it again. $0.001 a call.