Implement a customer-context connection

This guide is for the developer implementing a customer's Customer context connection. The product guide explains the settings; the separate API reference defines the conversation.init request and response schemas.

Agree on the behavior firstCopy Anchor Link

Decide with the person configuring the agent:

• Which information the agent should receive, such as an order status or appointment details.
• Which customers may see that information and how your service will check access.
• Whether automatic handling should continue when your service is unavailable.
• Whether information is needed only at conversation start or must be refreshed later through a tool.

The connection runs once when a new conversation starts. Follow-up messages reuse the saved result, and updated settings apply to new conversations.

Implement the callbackCopy Anchor Link

Chatbyte sends a signed HTTPS POST to your service with the event name conversation.init. It includes the agent, conversation, channel, and available customer identifiers. Your endpoint returns a decision and any permitted context in the same response.

Use the Conversation Initialization section of the API reference for signature verification, channel-specific fields, response limits, and examples. Your endpoint must be publicly reachable over HTTPS and respond within five seconds for Widget/email or three seconds for voice.

Returned information belongs to the conversation; saved contact profiles are managed separately. Authenticate the customer and check their access in your service before returning personal information.

Prompt variables and language overridesCopy Anchor Link

Widget and email prompts support the same {{variable_name}} syntax as voice. Each fields entry supplies its value; dynamicValues wins when both define the same name. Both override the built-in value for that name. For example:

{
  "version": "1.0",
  "decision": "continue",
  "fields": { "plan": { "value": "Pro" } },
  "dynamicValues": { "contact_first_name": "Ada" },
  "overrides": {
    "additionalSystemPrompt": "Address {{contact_first_name}} by name when natural. Their plan is {{plan}}.",
    "chat": {
      "languagePolicy": { "mode": "selected", "languages": ["de", "en"] }
    }
  }
}

Use {"mode":"auto"} to follow the customer's language. languagePolicy supports every language available in the agent settings and takes precedence over the legacy chat.language field. The effective policy also applies to server-written handoff and fallback messages.

Auto can include an optional starting language: {"mode":"auto","fallbackLanguage":"de"}. It applies only before the conversation establishes a language; a customer's clear message or explicit language request takes precedence. Without it, Auto falls back to the browser language when available, then English. An override replaces the whole language policy, so {"mode":"auto"} also clears a saved starting language for that conversation.

systemPrompt replaces the agent's business instructions; additionalSystemPrompt appends conversation-specific instructions. In chat, those additional instructions take precedence where they differ from the saved or replacement business prompt. Neither replaces platform rules or tool permissions. Context fields and variable values remain data, not instructions. In chat, the runtime binds named variable references to a separate context message; it does not paste customer values into privileged instructions.

Missing variables are not printed to customers. If a missing value is necessary, the assistant asks for it. Context carries its resolution timestamp and is bounded for the model. Supply concise, relevant fields. A saved initialization snapshot is not a current order status or balance; expose a tool when those facts need a fresh lookup. Reusing the conversation does not rerun initialization.

Test and hand overCopy Anchor Link

1. Give the administrator the endpoint and signing secret through an appropriate secure channel.
2. Use Test connection in Chatbyte with sample input. Requests carry test: true; handle them without sending messages or changing customer records.
3. Confirm the displayed result, then save the connection.
4. Have the administrator enable the intended channels and choose the failure behavior.
5. Start a new conversation and inspect API activity together.

After saving the endpoint, enable each intended channel. An API-requested stop prevents automatic handling. Configure human assignment and notifications separately for conversations that need the team.

Existing customer-context integrationsCopy Anchor Link

Older integrations may use customer.context.resolve, which runs per accepted Widget/email message rather than once at conversation start. Update and test the endpoint before saving channel settings that switch it to conversation.init.

A voice initialization binding takes precedence over the older voice.callInit callback for that agent. If your integration relies on the old callback, review that transition with the administrator before enabling it.