> Tychron Atlas API & Provisioning Reference — chapter 19 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/messaging-auto-responses/
> Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it).
> Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled)
> Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/
> Machine index: https://docs.tychron.com/llms.txt

# Messaging Auto Responses

## Schema

Messaging Auto Response

__Type__ Object

| Name          | Type                         | Description                       |
| ------------- | ---------------------------- | --------------------------------- |
| `id`          | String(format:uuid)          | [Desc. `id`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-299)           |
| `inserted_at` | String(format:date-time)     | An ISO8601 formatted timestamp    |
| `keywords`    | Array:[SubObject](https://docs.tychron.com/api-reference/messaging-auto-responses/#type-305) | [Desc. `keywords`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-306)     |
| `name`        | String                       | Display name of the Auto Response |
| `notes`       | String                       | Any notes about the auto response |
| `updated_at`  | String(format:date-time)     | An ISO8601 formatted timestamp    |

#### Desc. `id` {#desc-299}

A Universally unique identifier, which identifies the resource

#### SubObject {#type-305}

Sub-Schema

__Type__ Object

| Name          | Type    | Description                      |
| ------------- | ------- | -------------------------------- |
| `intercept`   | Boolean | [Desc. `intercept`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-300)   |
| `is_wildcard` | Boolean | [Desc. `is_wildcard`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-301) |
| `keyword`     | String  | [Desc. `keyword`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-302)     |
| `message`     | String  | [Desc. `message`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-303)     |
| `message2`    | String  | [Desc. `message2`](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-304)    |

#### Desc. `intercept` {#desc-300}

Should the messaging system intercept (i.e. not forward to switch) the message?

This can be useful for cases where the keyword is to be handled by the messaging system, but the destination switch can't or does not wish to handle the message.

#### Desc. `is_wildcard` {#desc-301}

Should this keyword be treated as a wildcard or fallback?

Only one wildcard can exist in a auto response, and will be returned for ALL messages that do not match any existing keywords.

Once is_wildcard is set, the keyword in question is also set to `WILDCARD`.

NOTE: To update an existing WILDCARD, the keyword must also be passed (i.e. `WILDCARD`).

#### Desc. `keyword` {#desc-302}

The word to trigger this specific keyword.

Note that when is_wildcard is true, keyword will always be `WILDCARD`.

#### Desc. `message` {#desc-303}

The primary message that should be sent as the reply.

In most scenarios this is the only message that needs to be set, however under the condition that a keyword is shared with the account's existing Keyword Plan (ask support for more information), the message may override it.

#### Desc. `message2` {#desc-304}

A secondary message which may be selected under certain circumstances.

If a keyword plan is active on the parent account, and the keyword has an OPTOUT or OPTIN behaviour, this message may be used.

In the case of an OPTIN action, this message will be used as the redundant action message (e.g. the subscriber has already opted in or already opted out of the messaging platform).





#### Desc. `keywords` {#desc-306}

A list of keywords that the auto response has, keywords are stored in uppercase, but are case insensitive upon usage.



__Example__

```json
{
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "keywords": [
    {
      "intercept": false,
      "is_wildcard": false,
      "keyword": "START",
      "message": "You have been opted in to receive messages from ACME Corp.\n",
      "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
    }
  ],
  "name": "My Auto Responder",
  "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```


## Summary

User customizable keyword plans, or auto responder.

## API

### Create Messaging Auto Response

```http
POST /api/v1/auto_responses HTTP/1.1
```

Create a new Messaging Auto Response.


#### Request application/json

```http
POST /api/v1/auto_responses HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 551
```

```json
{
  "data": {
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n"
  },
  "type": "messaging_auto_response"
}
```

#### Response 201

##### application/json

```http
HTTP/1.1 201
Content-Type: application/json
Content-Length: 700
```

```json
{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Update Messaging Auto Response

```http
PATCH /api/v1/auto_responses/{id} HTTP/1.1
```

Update an existing Messaging Auto Response


__Path Parameters__

| Name | Type                 | Description                |
| ---- | -------------------- | -------------------------- |
| id   | String(format:uuid)! | Messaging Auto Response ID |

#### Request application/json

```http
PATCH /api/v1/auto_responses/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 551
```

```json
{
  "data": {
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n"
  },
  "type": "messaging_auto_response"
}
```

#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 700
```

```json
{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Delete Messaging Auto Response

```http
DELETE /api/v1/auto_responses/{id} HTTP/1.1
```

Delete an existing Messaging Auto Response by ID.


__Path Parameters__

| Name | Type                 | Description                |
| ---- | -------------------- | -------------------------- |
| id   | String(format:uuid)! | Messaging Auto Response ID |

#### Request

```http
DELETE /api/v1/auto_responses/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 700
```

```json
{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### List Messaging Auto Responses

```http
GET /api/v1/auto_responses HTTP/1.1
```

Retrieve all Messaging Auto Responses for Account


__Query Parameters__

| Name   | Type    | Description                     |
| ------ | ------- | ------------------------------- |
| first  | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-307)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-308)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-309)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/messaging-auto-responses/#desc-310) |

#### Query Desc. first {#desc-307}

The number of items to return starting from the 'after' cursor

#### Query Desc. last {#desc-308}

The number of items to return behind the 'before' cursor

#### Query Desc. after {#desc-309}

The cursor representing the starting point of a 'first' based paging

#### Query Desc. before {#desc-310}

The cursor representing the starting point of a 'last' based paging

#### Request

```http
GET /api/v1/auto_responses HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 937
```

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "keywords": [
          {
            "intercept": false,
            "is_wildcard": false,
            "keyword": "START",
            "message": "You have been opted in to receive messages from ACME Corp.\n",
            "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
          }
        ],
        "name": "My Auto Responder",
        "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "messaging_auto_response"
    }
  ]
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```


### Get Messaging Auto Response

```http
GET /api/v1/auto_responses/{id} HTTP/1.1
```

Lookup an Messaging Auto Response by its ID


__Path Parameters__

| Name | Type                 | Description                |
| ---- | -------------------- | -------------------------- |
| id   | String(format:uuid)! | Messaging Auto Response ID |

#### Request

```http
GET /api/v1/auto_responses/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 700
```

```json
{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Attach Messaging Auto Response to DID

```http
PUT /api/v1/numbers/{number_id}/auto_response/{id} HTTP/1.1
```

Change or set a Number's Messaging Auto Response


__Path Parameters__

| Name      | Type                 | Description                |
| --------- | -------------------- | -------------------------- |
| number_id | String!              | Number or ID               |
| id        | String(format:uuid)! | Messaging Auto Response ID |

#### Request

```http
PUT /api/v1/numbers/{number_id}/auto_response/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 700
```

```json
{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Detach Messaging Auto Response from DID

```http
DELETE /api/v1/numbers/{number_id}/auto_response HTTP/1.1
```

Removes the Messaging Auto Response on a specified Number


__Path Parameters__

| Name      | Type    | Description  |
| --------- | ------- | ------------ |
| number_id | String! | Number or ID |

#### Request

```http
DELETE /api/v1/numbers/{number_id}/auto_response HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 700
```

```json
{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```

---

Previous chapter: https://docs.tychron.com/api-reference/switches.md  
Next chapter: https://docs.tychron.com/api-reference/dids.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt