Skip to main content
Social Intents
AI Action

Bring Your Own AI Agent

Already built an AI agent that knows your business and queries your own data in real time? Plug it into Social Intents live chat. Every visitor message goes to your endpoint, and your agent’s reply goes straight back to the visitor.

// Social Intents calls your agent
POST
https://agent.yourcompany.com/chat
{
  "sessionId": "8f3c...",
  "message": "Where is my order 10482?",
  "name": "Maria",
  "email": "maria@example.com"
}
// Your agent replies (HTTP 200)
{
  "response": "Order **10482** shipped today and
  should arrive Thursday."
}
// Shown to the visitor in the chat widget

What Is Bring Your Own Agent?

Most teams use the built-in Social Intents AI Agent, trained on their website and files. But if you have already built your own agent—with its own prompts, tools, and live access to your databases—you don’t need to rebuild it. Social Intents can act as the chat front end and send each visitor message to your agent instead.

It works with a single AI Action using the Auto trigger on every message trigger, on your website chat widget, WhatsApp, and Facebook Messenger. Social Intents handles the chat widget, inbox, Slack/Teams notifications, and human agents. Your agent handles the answers.

How It Works

1

Visitor sends a message

The visitor chats in your Social Intents widget as usual. A typing indicator appears right away.

2

We call your endpoint

Social Intents sends the message, a session ID, and any visitor details you choose to your HTTPS endpoint.

3

Your agent does the work

Your code runs your own model, prompts, and real-time lookups against your systems.

4

The reply goes to the visitor

Your JSON response is shown in the chat. The built-in AI model is skipped entirely.

Works With Any Agent You Can Reach Over HTTPS

Your own backend

Node.js, Python, Java, .NET, PHP—any service that accepts a POST and returns JSON.

Google Cloud

Agents running on Cloud Run or Cloud Functions, including agents built on Vertex AI.

AWS & Azure

Lambda, API Gateway, Azure Functions, or App Service endpoints.

Agent frameworks

LangChain, LangGraph, LlamaIndex, or your own OpenAI, Claude, or Gemini agent.

Workflow tools

n8n, Make, or any tool that can receive a webhook and respond with JSON.

Internal APIs

Rule-based bots or support systems you already run in-house.

Using a Google-managed agent such as Dialogflow CX? Those APIs need short-lived OAuth tokens, so put a small adapter service in front of them (see the Google Cloud tip below).

Step-by-Step Setup

First, make sure the AI Agent is turned on for your chat widget (the default OpenAI provider is fine—your agent answers instead). Then go to Chat Widgets → AI Agent → Actions, click Add Action, and fill in the fields below. AI Actions are available on the Pro and Business plans.

Field What to enter Example
Action type Choose Auto trigger on every message. Add only one of these per widget. Auto trigger on every message
Action name Any unique name using letters, numbers, and underscores. my_agent
Method Use POST so the message is sent in the request body. POST
Endpoint URL Your agent’s public HTTPS endpoint. https://agent.yourcompany.com/chat
Request headers A shared secret your endpoint checks. (JSON content type is set automatically.) Authorization: Bearer YOUR_SHARED_SECRET
Request JSON template The body to send. Use {{variable}} placeholders (see below). {"sessionId":"{{sessionId}}","message":"{{message}}"}
Response fields to use Optional. The path to the reply text if your response doesn’t use a standard field. ["data.reply"]

Request Format

With a Request JSON template, we send exactly that body with the placeholders filled in. Values are JSON-escaped for you, so keep each placeholder inside quotes.

{
  "sessionId": "{{sessionId}}",
  "chatId": "{{chatId}}",
  "message": "{{message}}",
  "name": "{{name}}",
  "email": "{{email}}",
  "phone": "{{phone}}"
}
Placeholder Value
{{message}} The visitor’s latest message.
{{sessionId}} Stays the same for the whole conversation (on WhatsApp, it’s tied to the visitor’s number). Use it to keep your agent’s memory per visitor.
{{chatId}} The Social Intents chat ID.
{{name}}, {{email}}, {{phone}} Visitor details from the pre-chat form or your site, when available.
{{transcript}} The full conversation so far as plain text, if your agent doesn’t keep its own history.
{{visitorCustom1}} … {{visitorCustom5}} Custom pre-chat fields, such as an account number.

No template? We send all available values as a flat JSON object, e.g. {"message":"...","name":"...","email":"...","sessionId":"...","chatId":"..."}.

Response Format

Return HTTP 200 with a JSON body. The simplest response is:

{ "response": "Your order shipped today and should arrive Thursday." }
  • Reply field: we look for response, data.response, message, text, or an OpenAI-style choices[0].message.content. For anything else, set Response fields to use to your path, like ["result.answer"] or ["messages[0].text"].
  • Formatting: Markdown (bold, lists, links) is converted to chat formatting. A value that starts with < and ends with > is sent as HTML.
  • Timing: respond within 60 seconds. Aim for a few seconds so the chat feels live.
  • Staying silent: return an empty object {} and no bot message is sent.
  • Errors: if your endpoint returns an error status or times out, the visitor never sees a technical error. We show your chatbot’s No-match response instead (plus its quick replies on web chat).

Best Practices

Key memory on sessionId

Each request carries one new message. Store conversation state by {{sessionId}}, or send {{transcript}} every time.

Secure your endpoint

Check a shared secret header on every request and reject anything without it.

Set a friendly fallback

In AI Agent settings, set a No-match response and quick replies in your visitors’ language. They’re shown if your endpoint is unavailable.

Test before going live

Try it on a test widget first and confirm replies, formatting, and your fallback all look right.

Tip: Agents on Google Cloud

If your agent is your own service on Cloud Run or Cloud Functions, point the Endpoint URL straight at it and check a shared secret header. If it’s a Google-managed agent API (Vertex AI agents, Dialogflow CX), those calls need a service-account OAuth token that expires hourly. Deploy a small adapter on Cloud Run that checks our header, calls your agent with the session ID, and returns {"response": "..."}: 

# main.py (Cloud Run, Python + Flask)
import os
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = os.environ["SI_SHARED_SECRET"]

@app.post("/chat")
def chat():
    if request.headers.get("Authorization") != f"Bearer {SECRET}":
        return jsonify(error="unauthorized"), 401
    body = request.get_json(force=True)
    # Call your agent here (Vertex AI, Dialogflow CX, your own model...)
    # using body["sessionId"] so the agent keeps the conversation context.
    reply = run_my_agent(body["sessionId"], body["message"])
    return jsonify(response=reply)

More AI Actions

Custom API

Let the built-in AI call your APIs
Escalation Routing

Route chats to the right team
All AI Actions

See everything your chatbot can do

Connect Your Own AI Agent Today

Keep your agent. Add live chat, an inbox, and human backup.

Start Free Trial