Scripts V2
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
draftorpublished. 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.
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.
The response includes the fields you need for the next edit:
Script types
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
- Read the script with
GET /v2/scripts/{scriptId}. Keep itsrevisionandconcurrencyVersion. - 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.
- Publish with
POST /v2/scripts/{scriptId}/publish. The draft becomes the live revision for new calls and messages.
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
409withERR_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
409with 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
409withERR_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.
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}andGET /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 return404. GET /v2/scripts/{scriptId}/revisionsand.../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
- Switch script creates and edits to
POSTandPUT /v2/scripts, and add apublishcall when the change should go live. Save and publish with the new id. - Move data extraction field changes into the script body.
- Handle
409 SCRIPTS_API_V2_REQUIREDfrom any V1 write you haven’t moved yet. - Update stored script ids that you compare against webhook or call data.
- Check the HTTP status before reading an error body. A
409can 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.
Questions about moving to Scripts V2? Contact support@meetgail.com.