--- name: "chat_setup" area: "chat" title: "Set up the website chat" price: "$0.001" method: "POST" url: "https://api.conecto.chat/v1/tools/chat_setup" mcp_server: "https://api.conecto.chat/mcp/chat" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/chat/chat_setup" --- # Set up the website chat (`chat_setup`) Creates or changes the business's website chat widget and who answers it, and returns the snippet for the website. Create or change the business's website chat widget, which you answer: each visitor message reaches you as a chat.message_received event (subscribe a webhook to it, or use chat_wait) and you reply with chat_reply. Or answer_with webhook: your own brain (your server, n8n, Flowise) gets each message as a signed POST and its reply goes to the visitor at once. Or answer_with model: a model on the business's own key answers, with instructions and knowledge you give. Conecto pays for no model in it. Only the fields you pass change. The reply has the HTML snippet to put on the website. $0.05 per conversation, charged on the visitor's first message; messages and replies are free. Price: $0.001 a call. A call that fails costs nothing. ## Use it when The business wants a chat on its website that the agent answers, one its existing chatbot (n8n, Flowise, its own server) answers through a webhook, or one a model answers on the business's own OpenAI, Anthropic or other key while no agent is online; or the widget's name, greeting, colour or language should change. - For the settings and snippet as they are now, use [chat_get_setup](https://conecto.chat/tools/chat/chat_get_setup.md). ## Say this to your agent > Put a chat on our website that you answer. Sign the replies Halverson Support and greet people with "Questions about a bike or a repair? Ask us." ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `name` | string | no | The business name. 1 to 120 characters. | | | | `website` | string | no | The website it goes on. Up to 255 characters. | | | | `greeting` | string | no | The first line visitors see. 1 to 300 characters. | | | | `agent_name` | string | no | The name your replies are signed with, e.g. "Acme Support". 1 to 60 characters. | | | | `color` | string | no | Accent colour, e.g. #1a73e8. Matches ^#[0-9a-fA-F]{6}$. | | | | `language` | string | no | Widget language, e.g. en, de. Matches ^[a-z]{2}$. | | | | `experience` | string | no | chat: the classic chat widget. beside: Beside, which also tells you the page the visitor is on (its address, title and text) with each message. Same price. | `"chat"`, `"beside"` | | | `starter_questions` | array of strings | no | Beside: up to 3 questions visitors can tap to start. Up to 3 items. | | | | `answer_with` | string | no | bot (the default): you answer through events and chat_reply. webhook: each visitor message is POSTed to webhook_url and its reply goes to the visitor at once. model: a model on the business's own key answers (model_provider, model, model_api_key). | `"bot"`, `"webhook"`, `"model"` | | | `webhook_url` | string | no | Your brain's https endpoint for each visitor message. Up to 500 characters. | | | | `webhook_token` | string | no | Sent as Authorization: Bearer, for brains that want a key (Flowise, n8n header auth). Empty removes it. Up to 500 characters. Stored encrypted and shown only as [redacted]. | | | | `rotate_secret` | boolean | no | Make a new webhook_secret (the old one stops working). | | `false` | | `cant_answer` | string | no | What the chat says when your webhook or model gave no reply; it then asks for the visitor's email. Needed for languages other than en, de, es, fr, it, nl, pt and sv. Up to 300 characters. | | | | `model_provider` | string | no | Whose model answers with answer_with model. | `"openai"`, `"anthropic"`, `"openrouter"`, `"mistral"`, `"groq"`, `"azure"` | | | `model` | string | no | The provider's model name, e.g. gpt-5.4-mini or claude-sonnet-5-5; for azure the deployment name. It must support tool calling. 1 to 160 characters. | | | | `model_api_key` | string | no | The business's API key for model_provider. Kept encrypted, never shown again; its usage is billed by the provider to the business. 1 to 500 characters. Stored encrypted and shown only as [redacted]. | | | | `model_base_url` | string | no | azure only: the resource's address, like https://acme.openai.azure.com/openai/v1/. Up to 300 characters. | | | | `instructions` | string | no | answer_with model: how the model answers (tone, scope, what to offer), in the business's words. Up to 4,000 characters. | | | | `knowledge` | string | no | answer_with model: facts it answers from (prices, delivery, opening hours). Replaces what was given before; empty removes it. The published help center is used as well. Up to 50,000 characters. | | | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `chat_setup` on the MCP server `https://api.conecto.chat/mcp/chat` with these arguments: ```json { "name": "Halverson Cycle & Repair", "website": "https://halversoncycle.example", "greeting": "Questions about a bike or a repair? Ask us.", "agent_name": "Halverson Support", "color": "#1f4d3a", "language": "en" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/chat_setup \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Halverson Cycle & Repair", "website": "https://halversoncycle.example", "greeting": "Questions about a bike or a repair? Ask us.", "agent_name": "Halverson Support", "color": "#1f4d3a", "language": "en"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "chat_setup", "status": "succeeded", "replayed": false, "cost_usd": "$0.001", "balance_usd": "$19.75", "result": { "chat": { "widget_id": 4101, "name": "Halverson Cycle & Repair", "website": "https://halversoncycle.example", "greeting": "Questions about a bike or a repair? Ask us.", "agent_name": "Halverson Support", "color": "#1f4d3a", "language": "en", "experience": "chat", "starter_questions": [], "embed_html": "", "install": "Put embed_html just before on every page of the website.", "answer_with": "bot", "answering": "You answer. Every visitor message arrives as a chat.message_received event: subscribe a webhook to it (notify_add_channel, then notify_subscribe with events [\"chat.*\"]) to get it on your server at once, or call chat_wait in a loop. Reply with chat_reply; chat_typing shows \"typing\" while you work. Conecto runs no AI of its own in the chat.", "listening": false, "pricing": { "model": "per conversation", "price_usd": "$0.05", "conversations_this_month": 0, "charged_this_month_usd": "$0.00", "unpaid": 0 } } } } ``` `result`: The widget: widget_id, name, website, greeting, agent name, colour, language, experience (chat or beside), starter questions, the embed_html to put before , who answers (answer_with; for a webhook its address, for a model its provider, model, instructions and knowledge size, and for both the last error) and how, whether it is listening, and this month's conversations and cost. webhook_secret comes back once, when a webhook is first set or rotated; a model key never comes back. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `invalid_input` | 400 | answer_with webhook came without an https webhook_url or with an address that is not public; answer_with model came without model_provider, model and model_api_key, or azure without its resource address; instructions or knowledge came while the bot answers; or cant_answer is missing for a language other than en, de, es, fr, it, nl, pt and sv. | Fix what the message names. Nothing was charged. | 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_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_reply](https://conecto.chat/tools/chat/chat_reply.md): Answers a website visitor as the business, with product cards, images or buttons if you like. 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.