We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

Messaging Auto Responses

Schema

Messaging Auto Response

Type Object

Name Type Description
id String(format:uuid) Desc. id
inserted_at String(format:date-time) An ISO8601 formatted timestamp
keywords Array:SubObject Desc. keywords
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

A Universally unique identifier, which identifies the resource

SubObject

Sub-Schema

Type Object

Name Type Description
intercept Boolean Desc. intercept
is_wildcard Boolean Desc. is_wildcard
keyword String Desc. keyword
message String Desc. message
message2 String Desc. message2

Desc. intercept

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

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

The word to trigger this specific keyword.

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

Desc. message

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

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

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

Example

{
  "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

POST /api/v1/auto_responses HTTP/1.1

Create a new Messaging Auto Response.

Request application/json

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

{
  "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/1.1 201
Content-Type: application/json
Content-Length: 700

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

{
  "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

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

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

{
  "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/1.1 200
Content-Type: application/json
Content-Length: 700

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

{
  "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

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

DELETE /api/v1/auto_responses/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "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

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
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Query Desc. first

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

Query Desc. last

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

Query Desc. after

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

Query Desc. before

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

Request

GET /api/v1/auto_responses HTTP/1.1
Accept: application/json

Response 200

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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

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

GET /api/v1/auto_responses/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

PUT /api/v1/numbers/{number_id}/auto_response/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

DELETE /api/v1/numbers/{number_id}/auto_response HTTP/1.1
Accept: application/json

Response 200

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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"
    }
  ]
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.