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

# Cancel Scheduled Messages

> Cancel messages scheduled with Trigger Chat that have not been sent yet.

Stop messages you scheduled with [Trigger Chat](/api-reference/chat/trigger) before they are sent. This works for WhatsApp, Web Chat and Email messages.

## Endpoint

```
DELETE https://api-v2.subverseai.com/api/chat-agent/cancel/{sessionId}
```

## Authentication

Every request needs your workspace API key in the `x-api-key` header.

```
x-api-key: your_workspace_api_key
```

You can create an API key from your dashboard. See [API Keys](/integrations/api-keys) for details.

## Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `sessionId` | Yes | The `sessionId` you got back from Trigger Chat when you scheduled the message. |

***

## Response

This API always returns `200`. Check `isCancelled` in the response to see whether anything was cancelled.

### Cancelled

The scheduled messages were stopped and won't be sent.

```json theme={null}
{
  "responseCode": 200,
  "message": "Scheduled messages cancelled successfully",
  "data": {
    "sessionId": "a3f1c9e2-7b4d-4e8a-9c21-5d6e7f8a9b0c",
    "isCancelled": true
  }
}
```

### Nothing to cancel

There are no pending messages for this conversation. The message may have already been sent, already been cancelled, or the `sessionId` may be incorrect.

```json theme={null}
{
  "responseCode": 200,
  "message": "No scheduled jobs found",
  "data": {
    "sessionId": "a3f1c9e2-7b4d-4e8a-9c21-5d6e7f8a9b0c",
    "isCancelled": false,
    "reason": "No scheduled jobs found for this session"
  }
}
```

### Could not cancel

The message couldn't be cancelled, usually because it is already being sent. `reason` gives more detail.

```json theme={null}
{
  "responseCode": 200,
  "message": "Jobs not cancelled",
  "data": {
    "sessionId": "a3f1c9e2-7b4d-4e8a-9c21-5d6e7f8a9b0c",
    "isCancelled": false,
    "reason": "..."
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | The conversation you asked to cancel. |
| `isCancelled` | boolean | `true` if scheduled messages were stopped, otherwise `false`. |
| `reason` | string | Only when `isCancelled` is `false`. Explains why nothing was cancelled. |

***

## Errors

| Status | `errorCode` | What it means |
| - | - | - |
| 401 | `apiKeyMissing` | The `x-api-key` header is missing. |
| 401 | `apiKeyInvalid` | The API key is not valid. |

***

## Code Examples

### cURL

```bash theme={null}
curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  https://api-v2.subverseai.com/api/chat-agent/cancel/SESSION_ID
```

### JavaScript

```javascript theme={null}
const response = await fetch(
  "https://api-v2.subverseai.com/api/chat-agent/cancel/SESSION_ID",
  {
    method: "DELETE",
    headers: { "x-api-key": "YOUR_API_KEY" },
  }
);

const result = await response.json();
console.log(result.data.isCancelled);
```

### Python

```python theme={null}
import requests

response = requests.delete(
    "https://api-v2.subverseai.com/api/chat-agent/cancel/SESSION_ID",
    headers={"x-api-key": "YOUR_API_KEY"},
)

print(response.json()["data"]["isCancelled"])
```

### Node.js (axios)

```javascript theme={null}
const axios = require("axios");

const { data } = await axios.delete(
  "https://api-v2.subverseai.com/api/chat-agent/cancel/SESSION_ID",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);

console.log(data.data.isCancelled);
```


## OpenAPI

````yaml DELETE /chat-agent/cancel/{sessionId}
openapi: 3.0.0
info:
  title: SubVerse API reference
  description: Detailed guide on how to use the SubVerse APIs
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-v2.subverseai.com/api
security:
  - ApiKeyAuth: []
paths:
  /chat-agent/cancel/{sessionId}:
    delete:
      tags:
        - Chat
      summary: Cancel scheduled messages
      description: Cancel messages scheduled with Trigger Chat that have not been sent yet.
      operationId: cancelScheduledChat
      parameters:
        - name: sessionId
          in: path
          required: true
          description: >-
            The `sessionId` returned by Trigger Chat when the message was
            scheduled.
          schema:
            type: string
            example: a3f1c9e2-7b4d-4e8a-9c21-5d6e7f8a9b0c
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              examples:
                cancelled:
                  summary: 200 - Scheduled messages cancelled
                  value:
                    responseCode: 200
                    message: Scheduled messages cancelled successfully
                    data:
                      sessionId: a3f1c9e2-7b4d-4e8a-9c21-5d6e7f8a9b0c
                      isCancelled: true
                nothing:
                  summary: 200 - Nothing scheduled
                  value:
                    responseCode: 200
                    message: No scheduled jobs found
                    data:
                      sessionId: a3f1c9e2-7b4d-4e8a-9c21-5d6e7f8a9b0c
                      isCancelled: false
                      reason: No scheduled jobs found for this session
        '401':
          description: API key missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              examples:
                apiKeyMissing:
                  summary: 401 - API key missing
                  value:
                    responseCode: 401
                    errorCode: apiKeyMissing
                    message: API key missing
                    data: null
                apiKeyInvalid:
                  summary: 401 - Invalid API key
                  value:
                    responseCode: 401
                    errorCode: apiKeyInvalid
                    message: Invalid API key
                    data: null
components:
  schemas:
    ApiResponse:
      type: object
      required:
        - responseCode
        - message
      properties:
        responseCode:
          type: integer
          description: >-
            Always returns 200 value, with error or success response details in
            message.
        message:
          type: string
          description: Success or error message with description.
        data:
          nullable: true
          description: Additional details if available.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Authentication header containing API key from SubVerse dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.