> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/developer-docs/generic-dialogue-provider/events.md). # Generic Dialogue Provider API events and callbacks Subscribe to Generic Dialogue Provider events and handle callback payloads. Generic Dialogue Provider posts event payloads to subscribed callback URLs when dialogue activity occurs. A dialogue must be connected before an agent can interact with it, and a subscription must exist before the external provider can receive events. GDP logs failed callback delivery. Do not depend on callback retries, request signing, shared-secret authentication, backoff, or guaranteed delivery unless these behaviors are explicitly supplied for the target environment. ## POST /api/v1/subscribe Subscribe a callback URL to Generic Dialogue Provider events. ### Authentication Requires: ```http Authorization: Bearer ``` ### Request body ```json { "callbackUrl": "https://example.com/gdp/events" } ``` | Field | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------------- | | `callbackUrl` | string | Yes | Public callback URL that receives event payloads. Must be a valid URI. | ### Response #### Success: 200 OK The response body is not guaranteed; do not depend on a response body for this status. #### Error responses | Status | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `400 Bad Request` | `callbackUrl` is not a valid URI or the request body is invalid. | | `401 Unauthorized` | The bearer token is missing or invalid. | | `409 Conflict` | The callback endpoint is already subscribed, there is already a subscription, or Generic Dialogue Provider settings are not available. | | `500 Internal Server Error` | The service could not process the request. | ## POST /api/v1/unsubscribe Unsubscribe from Generic Dialogue Provider events. ### Request This endpoint does not require a request body. ### Response #### Success: 200 OK The response body is not guaranteed; do not depend on a response body for this status. #### Error responses | Status | Description | | --------------------------- | ----------------------------------------------------- | | `401 Unauthorized` | The bearer token is missing or invalid. | | `409 Conflict` | Generic Dialogue Provider settings are not available. | | `500 Internal Server Error` | The service could not process the request. | ## Callback delivery GDP sends event payloads to subscribed callback URLs as JSON. GDP: * posts the event payload to each subscribed callback URL; * logs failed callback responses and exceptions; * returns `200 OK` to Dialogue Manager regardless of callback delivery success. Do not depend on retries, callback signing, shared-secret authentication, or delivery guarantees unless these behaviors are explicitly supplied for the target environment. ## Event envelope ```json { "timestamp": "2026-06-26T10:18:09.9461771+00:00", "name": "DialogueEvent", "type": "AgentConnected", "dialogueId": "0473cbce-cc9c-4afb-bb16-53fef61227b8", "payload": "sip:agent@example.com" } ``` | Field | Type | Description | | ------------ | -------------- | ----------------------------------------------------------------------------------------------- | | `timestamp` | string | Event timestamp. | | `name` | string | Event name. Example payloads use `DialogueEvent`. | | `type` | string | Event type. Valid values are `AgentConnected`, `NewMessage`, `AgentDisconnected`, and `Closed`. | | `dialogueId` | string | Dialogue ID related to the event. | | `payload` | string or null | Event-specific payload. | ## Event types ### AgentConnected Sent when an agent has picked up and accepted the queue item in WebAgent. ```json { "timestamp": "2026-06-26T10:18:09.9461771+00:00", "name": "DialogueEvent", "type": "AgentConnected", "dialogueId": "0473cbce-cc9c-4afb-bb16-53fef61227b8", "payload": "sip:agent@example.com" } ``` ### NewMessage Sent when a response to the inbound message is created. This can occur after a reply in WebAgent or after a reply from Dialogue Studio when Dialogue Studio is enabled. ```json { "timestamp": "2026-06-26T10:19:12.1120000+00:00", "name": "DialogueEvent", "type": "NewMessage", "dialogueId": "0473cbce-cc9c-4afb-bb16-53fef61227b8", "payload": "f75ad340-b918-436b-abcc-4682eb73edd5" } ``` For `NewMessage`, `payload` contains the message ID. ### AgentDisconnected Sent when the agent disconnects by transferring the dialogue to a skill. ```json { "timestamp": "2026-06-26T10:20:30.0000000+00:00", "name": "DialogueEvent", "type": "AgentDisconnected", "dialogueId": "0473cbce-cc9c-4afb-bb16-53fef61227b8", "payload": "sip:agent@example.com" } ``` ### Closed Sent when the dialogue is closed. A dialogue can close when: * the agent handled the dialogue in WebAgent; * `POST /api/v1/dialogue/{dialogueId}/disconnect` is used; * Dialogue Studio is enabled and a `disconnect` end node is called. ```json { "timestamp": "2026-06-26T10:25:00.0000000+00:00", "name": "DialogueEvent", "type": "Closed", "dialogueId": "0473cbce-cc9c-4afb-bb16-53fef61227b8", "payload": null } ``` ## Related topics * [Authentication](/developer-docs/generic-dialogue-provider/authentication.md) * [Messages, dialogues, and attachments](/developer-docs/generic-dialogue-provider/messages-and-dialogues.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://atlas.anywhere.now/developer-docs/generic-dialogue-provider/events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.