> ## Documentation Index > Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Remove a queued message > Removes a queued message before the agent picks it up, so the agent never sees it. Fails once the message has been sent. ## OpenAPI ````yaml /widgets-api-spec.yml post /v1/conversations/{id}/queued_messages/{queuedMessageId}:remove openapi: 3.1.0 info: title: Cadenya Widgets API description: >- Browser-facing API for the embeddable Cadenya chat widget. The customer's backend authenticates the visitor and creates the initial session. The browser renews that same session through RenewWidgetSession using its existing bearer token and required workspace ID, with no session ID in the request. Both return tokenExpiresAt and sessionExpiresAt; renewal never extends the session deadline. Renewal requires a valid token with 60 seconds of clock-skew tolerance; hard session expiry has no tolerance. Management credentials remain server-side. Terminal session errors never create a replacement. The only unauthenticated route is the widget config. version: '1.0' servers: - url: https://{widgetHost} description: The Widget host returned in a Widget Session's info.host variables: widgetHost: default: adbtaawrmh4h.widgets.cadenya.com security: - bearerAuth: [] tags: - name: WidgetConfigService description: |- Serves the widget's presentation config. The only unauthenticated surface: the widget is identified by the hostname and the edge enforces the origin allowlist; no session or token is required. - name: WidgetConversationEventStreamsService description: |- Server-streaming events over SSE. A separate service so deployments can route it around the JSON transcoder to a dedicated stream server — the transcoder cannot produce text/event-stream. - name: WidgetConversationService description: |- Conversations between the session's visitor and the widget's agent. All routes are token-implicit: scope comes entirely from the bearer's claims, and a conversation outside that scope 404s indistinguishably from one that does not exist. - name: WidgetSessionService description: |- Renews the caller's existing session token. Session identity comes only from the verified bearer token; no caller-supplied ID selects a session. paths: /v1/conversations/{id}/queued_messages/{queuedMessageId}:remove: post: tags: - WidgetConversationService - Conversations summary: Remove a queued message description: >- Removes a queued message before the agent picks it up, so the agent never sees it. Fails once the message has been sent. operationId: WidgetConversationService_RemoveQueuedMessage parameters: - name: id in: path description: Conversation ID. required: true schema: type: string - name: queuedMessageId in: path description: The queued message to remove. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RemoveQueuedMessageRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/WidgetQueuedMessage' '401': description: >- Unauthenticated. TOKEN_EXPIRED identifies verified access-token expiry at or beyond exp + 60 seconds before execution. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. Never retry renewal recursively. Missing, malformed, or invalid tokens do not authorize renewal. content: application/json: schema: $ref: '#/components/schemas/Status' '403': description: >- Permission denied. SESSION_REVOKED or SESSION_EXPIRED is terminal. Management authorization failures never trigger visitor-token renewal. content: application/json: schema: $ref: '#/components/schemas/Status' '429': description: >- Resource exhausted. SESSION_EXHAUSTED is terminal; rate limiting uses a distinct reason and may include Retry-After. content: application/json: schema: $ref: '#/components/schemas/Status' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: typescript label: TypeScript source: >- import CadenyaWidgets from '@cadenya/widgets'; const client = new CadenyaWidgets(); const result = await client.conversations.removeQueuedMessage('_123', { queuedMessageId: "sample" }); - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tcadenyawidgets \"go.cadenya.com/cadenya-widgets-go\"\n)\n\nfunc main() {\n\tclient, err := cadenyawidgets.NewClient()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tctx := context.Background()\n\tparams := &cadenyawidgets.ConversationRemoveQueuedMessageParams{\n\t\tQueuedMessageID: \"sample\",\n\t}\n\tresult, err := client.Conversations().RemoveQueuedMessage(ctx, \"_123\", params)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Printf(\"%+v\\n\", result)\n}" - lang: python label: Python source: |- from cadenya_widgets import CadenyaWidgets with CadenyaWidgets() as client: result = client.conversations.remove_queued_message("_123", queued_message_id="sample") print(result) - lang: ruby label: Ruby source: >- require "cadenya-widgets" client = CadenyaWidgets::Client.new result = client.conversations.remove_queued_message("_123", queued_message_id: "sample") puts result.inspect - lang: bash label: CLI source: |- cadenya-widgets conversations remove-queued-message _123 \ --queued-message-id sample - lang: shell label: curl source: |- curl --request POST \ --url '/v1/conversations/_123/queued_messages/queued_message_123:remove' \ --header "Authorization: Bearer ${CADENYAWIDGETS_API_KEY}" components: schemas: RemoveQueuedMessageRequest: type: object properties: id: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: Conversation ID. queuedMessageId: readOnly: true example: objqa_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The queued message to remove. description: Remove queued message request. WidgetQueuedMessage: required: - id - conversationId - content - state - createdAt type: object properties: id: readOnly: true example: objqa_01HXKD2E5NQM3T9AYWCFQAZGFV type: string conversationId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The conversation the message was sent to. content: readOnly: true type: string description: The message text. state: readOnly: true enum: - STATE_UNSPECIFIED - STATE_QUEUED - STATE_SENT - STATE_REMOVED - STATE_DISCARDED type: string format: enum createdAt: readOnly: true type: string format: date-time sentAt: readOnly: true type: string description: >- When the agent picked the message up. Unset until the message is sent. format: date-time eventId: readOnly: true type: string description: The userMessage event the message became once sent. description: |- WidgetQueuedMessage is a visitor message sent while the agent was responding. The agent picks queued messages up in order before its next reply; until then a queued message can be removed and the agent never sees it. Once sent, it arrives on the event stream as a userMessage event. Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: anyOf: - $ref: '#/components/schemas/WidgetSessionErrorInfo' - $ref: '#/components/schemas/GoogleProtobufAny' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). WidgetSessionErrorInfo: type: object description: >- google.rpc.ErrorInfo detail for widget lifecycle failures. Match both domain and reason; ignore unknown reasons rather than renewing automatically. required: - '@type' - domain - reason properties: '@type': type: string enum: - type.googleapis.com/google.rpc.ErrorInfo domain: type: string enum: - api.cadenya.com reason: $ref: '#/components/schemas/WidgetSessionErrorReason' metadata: type: object additionalProperties: type: string description: Optional non-sensitive context. Never contains tokens or secrets. GoogleProtobufAny: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. WidgetSessionErrorReason: type: string description: >- TOKEN_EXPIRED identifies access-token expiry beyond the 60-second clock-skew tolerance. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. SESSION_* reasons are terminal. Never infer renewability from HTTP status alone. enum: - TOKEN_EXPIRED - SESSION_REVOKED - SESSION_EXPIRED - SESSION_EXHAUSTED securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.