---
title: "Create SWML Script"
method: POST
path: "/api/fabric/resources/swml_scripts"
tags: ["SWML Scripts"]
---

# Create SWML Script

`POST /api/fabric/resources/swml_scripts`

Creates a resource that stores a calling or messaging SWML document in SignalWire. Use it for versioned instructions that can run without fetching content from your server; choose [Create SWML webhook](/docs/apis/rest/swml-webhook/create-swml-webhook) when your server must generate different SWML for each request, or [Create cXML Script](/docs/apis/rest/cxml-scripts/create-cxml-script) for cXML applications.

#### Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_, _Messaging_, _Fax_, or _Video_.

[Learn more about API scopes](/docs/platform/your-signalwire-api-space).

## Request body

- union — Body shape for creating a SWML Script. Choose a [Calling Script](#schema/CallingSwmlScriptCreateRequest) for inbound or outbound calls or a [Messaging Script](#schema/MessagingSwmlScriptCreateRequest) for inbound SMS or MMS messages. `script_type` is optional and defaults to `"calling"` when omitted — set it explicitly to `"messaging"` to create a Messaging Script. The script kind determines whether the script can be assigned as a call handler or a message handler on a phone number.
  - CallingSwmlScriptCreateRequest — Request body to create a SWML Script that handles inbound or outbound calls.
    - `name` string, required — Display name of the SWML Script
    - `script_type` 'calling' — Set to `calling` for a Calling Script. This is the default when `script_type` is omitted.
    - `contents` object, required — The calling SWML document. Uses [calling SWML methods](/docs/swml/reference/calling).
    - `status_callback_url` string, uri — URL that receives status callbacks for messages sent or calls made by this script.
  - MessagingSwmlScriptCreateRequest — Request body to create a SWML Script that handles inbound SMS or MMS messages.
    - `name` string, required — Display name of the SWML Script
    - `script_type` 'messaging' — Set to `messaging` to create a Messaging Script. If omitted, the API defaults to `calling`, so this field must be set explicitly for messaging scripts.
    - `contents` object, required — The messaging SWML document. Uses [messaging SWML methods](/docs/swml/reference/messaging).

## Response `200`

The request has succeeded.

- SwmlScriptResponse
  - `id` string, uuid, required — Universal Unique Identifier.
  - `project_id` string, uuid, required — Universal Unique Identifier.
  - `display_name` string, required — Display name of the SWML Script Fabric Resource
  - `type` 'swml_script', required — Type of the Fabric Resource
  - `created_at` string, date-time, required — Date and time when the resource was created.
  - `updated_at` string, date-time, required — Date and time when the resource was updated.
  - `swml_script` union, required — A SWML Script — either a [Calling Script](#schema/CallingSwmlScript) for inbound or outbound calls, or a [Messaging Script](#schema/MessagingSwmlScript) for inbound SMS or MMS messages. The `script_type` field on each script (`"calling"` or `"messaging"`) identifies which kind it is.
    - CallingSwmlScript — A SWML Script that handles inbound or outbound calls. The `contents` field carries a [calling SWML document](/docs/swml/reference/calling).
      - `id` string, uuid, required — Universal Unique Identifier.
      - `display_name` string, required — The displayed name of the SWML script.
      - `script_type` 'calling', required — Set to `calling` for SWML Scripts that handle inbound or outbound calls.
      - `request_url` string, uri, required — URL where this SWML Script is hosted.
      - `contents` object, required — The calling SWML document executed when this script runs. Uses [calling SWML methods](/docs/swml/reference/calling).
      - `status_callback_url` string, uri — URL that receives status callbacks for messages sent or calls made by this script.
      - `status_callback_method` 'POST' — HTTP method used for status callbacks.
    - MessagingSwmlScript — A SWML Script that handles inbound SMS or MMS messages. The `contents` field carries a [messaging SWML document](/docs/swml/reference/messaging).
      - `id` string, uuid, required — Universal Unique Identifier.
      - `display_name` string, required — The displayed name of the SWML script.
      - `script_type` 'messaging', required — Set to `messaging` for SWML Scripts that handle inbound SMS or MMS messages.
      - `request_url` string, uri, required — URL where this SWML Script is hosted.
      - `contents` object, required — The messaging SWML document executed when this script runs. Uses [messaging SWML methods](/docs/swml/reference/messaging).

## Other responses

- `401` — Access is unauthorized.
- `404` — The server cannot find the requested resource.
- `422` — The request contains invalid parameters. See errors for details.
- `500` — An internal server error occurred.

## Changes

> 137 revisions in range; 3 could not be searched.

- **2026-08-20** `e79dcc8b2150` — 6 breaking, 2 warning, 4 info
  - the `oneOf[subschema #1: Create Calling Script]/contents` request property type/format changed from ``/`` to `object`/``
  - the `oneOf[subschema #2: Create Messaging Script]/contents` request property type/format changed from ``/`` to `object`/``
  - added 'unevaluatedProperties' constraint to the request property `oneOf[subschema #1: Create Calling Script]/contents`
  - added 'unevaluatedProperties' constraint to the request property `oneOf[subschema #2: Create Messaging Script]/contents`
  - …8 more
- …earlier changes not shown

[Full history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/fabric/resources/swml_scripts/post.md)

---

[API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/revisions/792d5b8e2970/schema)