> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke (Sync)

> Send customer input events to an AI agent and receive a single aggregated JSON response without streaming 🫴

Use this endpoint when you want the agent's complete reply in a single JSON response rather than a streaming NDJSON body. Useful for server-to-server integrations where streaming is inconvenient. You must [initialise a session](/ai/agent-graph/init-session) before calling this endpoint.

## Endpoint

```json theme={null}
POST https://api.connectly.ai/external/v1/ai/agent_graph/invoke_sync
```

## Request body

Same as Invoke (Stream) — `businessId`, `clientKey`, `sessionId`, optional `agentId`, and `inputEvents` with the same supported event types.

## Response

<ResponseField name="response.sessionId" type="string">
  The session ID for this conversation.
</ResponseField>

<ResponseField name="response.responseEvents" type="array">
  All agent response events returned in a single array. Each element contains exactly one event key:

  <Expandable title="messageEvent">
    A text, audio, image, or location message from the agent.
  </Expandable>

  <Expandable title="recommendationEvent">
    A list of product recommendations from the agent.

    | Field                    | Type   | Description                   |
    | ------------------------ | ------ | ----------------------------- |
    | `products[].productId`   | string | Connectly product identifier. |
    | `products[].title`       | string | Product name.                 |
    | `products[].description` | string | Product description.          |
    | `products[].url`         | string | Product page URL.             |
    | `products[].imageUrl`    | string | Product image URL.            |
    | `products[].price`       | number | Product price.                |
    | `products[].currency`    | string | ISO 4217 currency code.       |
  </Expandable>

  <Expandable title="chatSuggestionEvent">
    Suggested follow-up questions for the customer.

    | Field                | Type      | Description                         |
    | -------------------- | --------- | ----------------------------------- |
    | `suggestedQuestions` | string\[] | List of suggested question strings. |
  </Expandable>

  <Expandable title="agentHandoverEvent">
    Signals the conversation should be handed over to a human agent.

    | Field             | Type    | Description                        |
    | ----------------- | ------- | ---------------------------------- |
    | `triggerHandover` | boolean | Whether to initiate a handover.    |
    | `reason`          | string  | Reason for handover (English).     |
    | `reasonNative`    | string  | Reason in the customer's language. |
  </Expandable>

  <Expandable title="connectlyInteractiveEvent">
    An interactive WhatsApp message. The `interactive` object contains one of: `listMessage`, `replyButtonMessage`, `singleProductMessage`, or `multiProductMessage`.
  </Expandable>

  <Expandable title="sessionCloseEvent">
    Indicates the agent has ended the session. An empty object `{}`.
  </Expandable>
</ResponseField>

## Example

```http theme={null}
POST /external/v1/ai/agent_graph/invoke_sync HTTP/1.1
Host: api.connectly.ai
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "businessId": "your-business-id",
  "clientKey": "customer-123",
  "sessionId": "your-session-id",
  "inputEvents": [
    {
      "messageEvent": {
        "role": "USER",
        "content": { "textContent": { "text": "What are your store hours?" } }
      }
    }
  ]
}
```

```json theme={null}
{
  "response": {
    "sessionId": "your-session-id",
    "responseEvents": [
      {
        "messageEvent": {
          "role": "ASSISTANT",
          "content": { "textContent": { "text": "We're open Monday–Friday, 9am–6pm." } }
        }
      }
    ]
  }
}
```