Skip to navigation

Scripts V2

View as Markdown

Scripts V2 gives every script a draft and a version history. You edit a draft without changing live calls, then publish it when it’s ready. Calls and messages always use the latest published revision.

New organizations start on Scripts V2. Existing organizations move when they upgrade, which an admin can do from the Gail portal once the upgrade is offered to them. The upgrade is permanent. If you have questions, contact support@meetgail.com.

The endpoints are listed under Scripts V2 in the API Reference. They use the same X-API-Key authentication as the rest of the API.

How scripts work in V2

  • Id. Each script has one id that never changes across revisions.
  • Revisions. Every save is stored as a numbered revision, starting at 1. Revisions are never edited after they’re published.
  • Revision state. A revision is either draft or published. A script has at most one draft at a time, and it’s always the newest revision.
  • What calls use. Calls and messages use the latest published revision, never the draft.
  • Actions belong to the script. A phone script’s actions (use cases) and data extraction fields are part of the script itself. Editing one script never changes another.
You want toCall
Create a scriptPOST /v2/scripts (publishes revision 1)
Read the newest revision, draft or publishedGET /v2/scripts/{scriptId}
Save changes as a draftPUT /v2/scripts/{scriptId}
Make the draft livePOST /v2/scripts/{scriptId}/publish
See the historyGET /v2/scripts/{scriptId}/revisions
Read one revisionGET /v2/scripts/{scriptId}/revisions/{revision}
List scriptsGET /v2/scripts
Archive or restorePOST /v2/scripts/{scriptId}/archive, POST /v2/scripts/{scriptId}/restore

Create a script

Send the whole script. type, name and direction are required for every type. The new script is published right away as revision 1, and the response has status 201.

curl -X POST https://api.meetgail.com/v2/scripts \
-H "X-API-Key: your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"type": "phone",
"name": "Policy renewal reminder",
"direction": "outbound",
"agentName": "Gail",
"greeting": "Hi, this is Gail calling from {Organization Name}.",
"goodbye": "Thanks for your time. Have a great day.",
"useCases": [
{
"order": 1,
"status": "active",
"title": "Confirm renewal",
"description": "Use this when the customer is ready to talk about their renewal.",
"actions": [
{ "type": "default", "description": "Confirm the policy number and renewal date." }
]
}
]
}'

The response includes the fields you need for the next edit:

{
"type": "phone",
"id": "01a1f00e-f9e3-7c11-9d2a-5b6e8f7a9c10",
"revision": 1,
"revisionState": "published",
"concurrencyVersion": 1,
"publishedAt": "2026-11-19T15:04:05Z",
"archived": false,
"...": "..."
}

Script types

typeRequired fieldsUse it for
phoneagentName, goodbye, useCasesAI phone calls, inbound or outbound
textmessageText messages
emailsubject, bodyEmails
blastermessagePre-recorded phone messages

Phone scripts also accept FAQs, knowledge base settings, voice settings, post-call scripts and dataExtractionFields. See the request schema in the API Reference for every field.

Edit and publish

  1. Read the script with GET /v2/scripts/{scriptId}. Keep its revision and concurrencyVersion.
  2. Save a draft with PUT /v2/scripts/{scriptId}, sending the whole script, not just the fields you changed.
    • If the newest revision is published, the save starts a new draft revision.
    • If a draft already exists, the save replaces its content and keeps its revision number.
  3. Publish with POST /v2/scripts/{scriptId}/publish. The draft becomes the live revision for new calls and messages.
# Save a draft, refusing the save if someone changed the script since you read it
curl -X PUT "https://api.meetgail.com/v2/scripts/$SCRIPT_ID?expectedRevision=1&expectedConcurrencyVersion=1" \
-H "X-API-Key: your-api-key-here" \
-H "Content-Type: application/json" \
-d @script.json
# Publish the draft you just saved (use the revision and concurrencyVersion the save returned)
curl -X POST "https://api.meetgail.com/v2/scripts/$SCRIPT_ID/publish?expectedRevision=2&expectedConcurrencyVersion=1" \
-H "X-API-Key: your-api-key-here"

Only a draft can be published. Publishing when the newest revision is already published returns 400 with ERR_SCRIPT_NOT_DRAFT.

Avoid overwriting someone else’s changes

PUT and publish accept expectedRevision and expectedConcurrencyVersion as query parameters. Send the values from the response you last read:

  • If someone else saved or published since then, the request returns 409 with ERR_SCRIPT_CHANGED, and nothing is changed. Read the script again and reapply your edit.
  • Send both values or neither. Sending only one returns 400.
  • Without them, the last write wins. If two writes land at the same moment, one of them can get a 409 with no body. Read the script again and retry.

concurrencyVersion starts at 1 for each revision and changes on every save, publish and archive, so always use the value from your most recent response.

Archive and restore

POST /v2/scripts/{scriptId}/archive stops a script from being edited. Restoring it with POST /v2/scripts/{scriptId}/restore makes it editable again.

  • Archiving doesn’t break anything already using the script. Campaigns, sequences, inbound routing and tools that reference it keep working.
  • An archived script can’t be saved or published until it’s restored. Those requests return 409 with ERR_SCRIPT_ARCHIVED.
  • A save that adds or keeps a reference to an archived script is refused with ERR_SCRIPT_ARCHIVED_REFERENCE, and the error names the script.
  • Both calls are safe to repeat. Archiving an archived script, or restoring an active one, returns 200.

List scripts

GET /v2/scripts returns the newest revision of each script, 50 at most per page.

ParameterDescription
limitPage size, 1 to 50. Default 50.
after / beforeCursor: a script id from the previous page.
orderasc or desc by id. Default desc.
directioninbound or outbound.
statusactive or archived.

Move an integration from V1

What changes when an organization is on Scripts V2

Writes go to V2. For an organization on Scripts V2, every V1 script write returns 409 with the code SCRIPTS_API_V2_REQUIRED. That includes creating, updating and deleting scripts under /v1/scripts, and changing data extraction fields under /v1/data_extraction. Use the V2 endpoints instead. Data extraction fields go in the script body as dataExtractionFields.

Reads keep working. GET /v1/scripts and GET /v1/scripts/{scriptId} return the published V2 scripts.

Script ids change once, at the upgrade. When an existing organization upgrades, each script gets a new id. The old id still works for reads and for starting calls, but not for edits:

  • GET /v1/scripts/{scriptId} and GET /v2/scripts/{scriptId} accept the old id or the new one. Responses always carry the new id.
  • Starting calls, outreaches and sequences accept either id.
  • Archive and restore accept either id.
  • Saving (PUT /v2/scripts/{scriptId}) and publishing need the new id. Sent the old id, they return 404.
  • GET /v2/scripts/{scriptId}/revisions and .../revisions/{revision} need the new id.

If your integration stored script ids before the upgrade, read each script with GET /v2/scripts/{scriptId} and use the id it returns for every save and publish.

Webhooks and call data use the new id. After the upgrade, call_information.script_id in call webhooks and in the calls API is the new id. call_information.script_revision_number tells you which revision the call ran.

If your integration compares script_id against ids it saved earlier, for example to route calls in a CRM or to filter a report, update those saved ids after the upgrade. The easiest way is to look each saved id up with GET /v2/scripts/{scriptId} and store the id it returns.

Checklist

  1. Switch script creates and edits to POST and PUT /v2/scripts, and add a publish call when the change should go live. Save and publish with the new id.
  2. Move data extraction field changes into the script body.
  3. Handle 409 SCRIPTS_API_V2_REQUIRED from any V1 write you haven’t moved yet.
  4. Update stored script ids that you compare against webhook or call data.
  5. Check the HTTP status before reading an error body. A 409 can come back with no body (see Errors).

Errors

Most errors use the standard error response: an errors array whose entries carry a code, a title and a detail. Some 409 responses have no body, so check the HTTP status first and only read errors when the response has a JSON body.

StatusCodeMeaning
400ERR_SCRIPT_NOT_DRAFTPublish was called, but the newest revision is already published.
400ERR_PUBLISH_TOOLS_INVALIDThe draft references tools that are archived or missing. Remove them and publish again.
400ERR_SCRIPT_ARCHIVED_REFERENCEThe save references an archived script, which the error names.
400—The body is invalid, or only one of expectedRevision and expectedConcurrencyVersion was sent.
404—No script with that id in your organization, or a save or publish was sent the old id from before the upgrade.
409ERR_SCRIPT_ARCHIVEDThe script is archived. Restore it before saving or publishing.
409ERR_SCRIPT_CHANGEDSomeone saved or published the script since you read it.
409SCRIPTS_API_V2_REQUIREDA V1 script write for an organization on Scripts V2.
409(no body)Another write to the same script happened at the same moment. This can happen on save and publish without expectedRevision and expectedConcurrencyVersion, and on archive and restore. Read the script again and retry.

Questions about moving to Scripts V2? Contact support@meetgail.com.