> 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.md).

# Generic Dialogue Provider API

Generic Dialogue Provider API routes for messages, dialogues, attachments, and event subscriptions.

The Generic Dialogue Provider API lets an external dialogue provider create and manage messages and dialogues, connect a dialogue to a UCC (Unified Contact Center), manage message attachments, and receive dialogue events through a callback subscription.

Before implementing the API, [configure Generic Dialogue Provider](/channels-integrations/text-channels/generic-dialogue-provider.md) in Channels & integrations.

Endpoint paths use versioned routes under `/api/v1/`. The externally published host name, regional host names, and tenant-scoping model are deployment-specific and are not defined in this reference.

## Before you implement

Complete provider enablement and UCC setup before implementing the API.

{% content-ref url="/spaces/iTek8gfJMjuAJhfqvtuU/pages/715tCr24P1kMqKopqkWf" %}
[Configure Generic Dialogue Provider](/channels-integrations/text-channels/generic-dialogue-provider.md)
{% endcontent-ref %}

Obtain the base URL, UCC ID, token endpoint, client ID, and client secret supplied for the target environment. Do not copy values from another environment.

## Implementation quickstart

Use this end-to-end navigation sequence:

1. Complete [Generic Dialogue Provider setup](/channels-integrations/text-channels/generic-dialogue-provider.md).
2. Obtain the credentials and environment-specific values supplied for the integration.
3. [Authenticate requests](/developer-docs/generic-dialogue-provider/authentication.md).
4. Use the API task reference to [create a dialogue](/developer-docs/generic-dialogue-provider/dialogues.md#post-api-v1-dialogue), [create a message](/developer-docs/generic-dialogue-provider/messages.md#post-api-v1-message), [link the message](/developer-docs/generic-dialogue-provider/messages.md#post-api-v1-message-messageid-link), [subscribe to events](/developer-docs/generic-dialogue-provider/events.md#post-api-v1-subscribe), and [connect the dialogue](/developer-docs/generic-dialogue-provider/dialogues.md#post-api-v1-dialogue-dialogueid-connect).
5. [Validate Generic Dialogue Provider](/channels-integrations/text-channels/generic-dialogue-provider.md#validate-generic-dialogue-provider) and confirm the expected callback through [Event subscriptions and callbacks](/developer-docs/generic-dialogue-provider/events.md).

## Optional Dialogue Studio Example

The public [Generic Dialogue Provider template](https://github.com/AnywhereNow/DialogueStudioFlows/tree/20ed6a8538ab29016d45caee7f48bf4e815c32ef/GenericDialogueProviderTemplate) illustrates API requests and a callback receiver. Dialogue Studio is optional; the API sequence above also applies to an adapter implemented in another environment.

Treat the template as a reference, not a production-ready integration. Its authentication function reads `AUTH_URL`, `AUTH_TENANT_ID`, and `AUTH_CLIENT_SECRET`; the diagnostic label `AUTH_TOKEN_URL` does not match the variable read. Set the correct `DS_PUBLIC_URL` rather than using the malformed `https:/INSTANCE.dialogue.studio` fallback. Review its instructions against the artifact and your Studio environment.

The example retains the latest dialogue ID in flow context, not separate state for concurrent sessions. Adapt that assumption before testing concurrent dialogues. Suggested retry extensions are not a GDP delivery or idempotency guarantee.

## Authentication

Most Generic Dialogue Provider API endpoints require a bearer token in the `Authorization` header:

```http
Authorization: Bearer <access-token>
```

Token acquisition depends on the current Authentication Service configuration for the environment. Use the token endpoint, client ID, and client secret provided for the Generic Dialogue Provider integration.

{% content-ref url="/pages/KTeUrxgvE17kWCicLCdO" %}
[Generic Dialogue Provider API authentication](/developer-docs/generic-dialogue-provider/authentication.md)
{% endcontent-ref %}

## Routes

| Method   | Path                                                    | Description                                    |
| -------- | ------------------------------------------------------- | ---------------------------------------------- |
| `POST`   | `/api/v1/message`                                       | Create an inbound or outbound message.         |
| `GET`    | `/api/v1/message/{messageId}`                           | Retrieve a message.                            |
| `PATCH`  | `/api/v1/message/{messageId}`                           | Update the external provider ID for a message. |
| `POST`   | `/api/v1/message/{messageId}/link`                      | Link a message to a dialogue.                  |
| `POST`   | `/api/v1/dialogue`                                      | Create a dialogue.                             |
| `GET`    | `/api/v1/dialogue/{dialogueId}`                         | Retrieve a dialogue and its message IDs.       |
| `POST`   | `/api/v1/dialogue/{dialogueId}/connect`                 | Connect a dialogue to a UCC.                   |
| `POST`   | `/api/v1/dialogue/{dialogueId}/disconnect`              | Disconnect a connected dialogue.               |
| `POST`   | `/api/v1/subscribe`                                     | Subscribe a callback URL to GDP events.        |
| `POST`   | `/api/v1/unsubscribe`                                   | Remove the current callback subscription.      |
| `POST`   | `/api/v1/message/{messageId}/attachment`                | Upload an attachment for a message.            |
| `GET`    | `/api/v1/message/{messageId}/attachment/{attachmentId}` | Download an attachment.                        |
| `DELETE` | `/api/v1/message/{messageId}/attachment/{attachmentId}` | Delete an attachment.                          |

## API task reference

{% content-ref url="/pages/KTeUrxgvE17kWCicLCdO" %}
[Generic Dialogue Provider API authentication](/developer-docs/generic-dialogue-provider/authentication.md)
{% endcontent-ref %}

{% content-ref url="/pages/HbAm3JZSQeqhp866XwEv" %}
[Generic Dialogue Provider API messages](/developer-docs/generic-dialogue-provider/messages.md)
{% endcontent-ref %}

{% content-ref url="/pages/zNjef31OOk1O1y9Zdeih" %}
[Generic Dialogue Provider API dialogues](/developer-docs/generic-dialogue-provider/dialogues.md)
{% endcontent-ref %}

{% content-ref url="/pages/9YYkKfF3O7ZI04M7IEnw" %}
[Generic Dialogue Provider API attachments](/developer-docs/generic-dialogue-provider/attachments.md)
{% endcontent-ref %}

{% content-ref url="/pages/2DauQF7Dyzh1LAKcMGJf" %}
[Generic Dialogue Provider API events and callbacks](/developer-docs/generic-dialogue-provider/events.md)
{% endcontent-ref %}

The [legacy combined API route](/developer-docs/generic-dialogue-provider/messages-and-dialogues.md) preserves existing endpoint links and routes readers to the canonical resource pages.

## Error handling

Endpoint tables list the defined status codes. Validation errors use the service validation response format. The response body is not guaranteed for all error statuses; do not depend on a response body unless the endpoint documents one. Some not-found and conflict responses forwarded from Dialogue Manager are wrapped as:

```json
{
  "error": "<raw response>"
}
```

Unhandled exceptions can return `500 Internal Server Error` without a documented response body.


---

# 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.md?ask=<question>&goal=<user_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.