Document Resource
A Sync Document is an object with these characteristics:
It's a single JSON object, up to 16KiB in size.
Its modification history is not maintained; however, documents are assigned a new revision number after each modification.
Its concurrency control is based on an 'eventual' model and it uses revision numbers for conditional updates.
It expires and is deleted automatically if its eviction is configured by setting the
ttl
parameter. By default, it is persisted permanently.
A Sync Document is best suited for basic use cases, such as rudimentary publish/subscribe flows, or situations where history synchronization is not a requirement.
Documents can be created, updated, subscribed to, and removed via the client JavaScript SDK . See the latest JavaScript SDK documentation for full details. Servers wishing to manage these objects can do so via the REST API.
Resource properties sid
type: SID<ET>
The unique string that we created to identify the Document resource.
unique_name
type: string
An application-defined string that uniquely identifies the resource. It can be used in place of the resource's sid
in the URL to address the resource and can be up to 320 characters long.
url
type: string<uri>
The absolute URL of the Document resource.
links
type: object<uri-map>
The URLs of resources related to the Sync Document.
revision
type: string
The current revision of the Sync Document, represented as a string. The revision
property is used with conditional updates to ensure data consistency.
data
type: object
An arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.
date_expires
type: string<date-time>
The date and time in GMT when the Sync Document expires and will be deleted, specified in ISO 8601(link takes you to an external page) format. If the Sync Document does not expire, this value is null
. The Document resource might not be deleted immediately after it expires.
date_created
type: string<date-time>
date_updated
type: string<date-time>
created_by
type: string
The identity of the Sync Document's creator. If the Sync Document is created from the client SDK, the value matches the Access Token's identity
field. If the Sync Document was created from the REST API, the value is system
.
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Documents
URI parameters Request body parameters UniqueName
type: string
An application-defined string that uniquely identifies the Sync Document
Data
type: object
A JSON string that represents an arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.
_11 // Download the helper library from https://www.twilio.com/docs/node/install
_11 // Find your Account SID and Auth Token at twilio.com/console
_11 // and set the environment variables. See http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .create({uniqueName: 'user_prefs'})
_11 .then(document => console.log(document.sid));
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "created_by": "created_by",
_16 "date_expires": "2015-07-30T21:00:00Z",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "revision": "revision",
_16 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "unique_name": "user_prefs",
_16 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_10 client.document('user_prefs').then(function(doc) {
_10 foregroundColor: "#ffff00",
_10 backgroundColor: "#ff0000"
Info Using set will overwrite any existing data in a document.
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
URI parameters Sid
type: string
The SID of the Document resource to fetch. Can be the Document resource's sid
or its unique_name
.
_11 // Download the helper library from https://www.twilio.com/docs/node/install
_11 // Find your Account SID and Auth Token at twilio.com/console
_11 // and set the environment variables. See http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .documents('ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(document => console.log(document.uniqueName));
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "created_by": "created_by",
_16 "date_expires": "2015-07-30T21:00:00Z",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "revision": "revision",
_16 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "unique_name": "unique_name",
_16 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_10 client.document('user_prefs').then(function(doc) {
_10 console.log(doc.value);
_10 syncClient.document("user_prefs").then(function(doc) {
_10 doc.on("updated",function(data) {
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Documents
Info By default, this will return the first 50 Documents. Specify a PageSize
value to fetch up to 100 items at once. See paging for more information.
URI parameters PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
The page token. This is provided by the API.
_11 // Download the helper library from https://www.twilio.com/docs/node/install
_11 // Find your Account SID and Auth Token at twilio.com/console
_11 // and set the environment variables. See http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(documents => documents.forEach(d => console.log(d.sid)));
_29 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29 "created_by": "created_by",
_29 "date_expires": "2015-07-30T21:00:00Z",
_29 "date_created": "2015-07-30T20:00:00Z",
_29 "date_updated": "2015-07-30T20:00:00Z",
_29 "revision": "revision",
_29 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29 "sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29 "unique_name": "unique_name",
_29 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29 "permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_29 "first_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=0",
_29 "next_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=1",
_29 "previous_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=0",
_29 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=0"
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
Request headers If-Match
type: string
The If-Match HTTP request header
URI parameters Sid
type: string
The SID of the Document resource to update. Can be the Document resource's sid
or its unique_name
.
Request body parameters Data
type: object
A JSON string that represents an arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.
_11 // Download the helper library from https://www.twilio.com/docs/node/install
_11 // Find your Account SID and Auth Token at twilio.com/console
_11 // and set the environment variables. See http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .documents('ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(document => console.log(document.uniqueName));
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "created_by": "created_by",
_16 "date_expires": "2015-07-30T21:00:00Z",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "revision": "revision",
_16 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "unique_name": "unique_name",
_16 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
This will modify the foregroundColor key in the Document
_10 client.document('user_prefs').then(function(doc) {
_10 doc.update({foregroundColor: "#ff0000"});
Use mutate for more fine grained control over updates.
_10 client.document('user_prefs').then(function(doc) {
_10 doc.mutate(function(remoteData) {
_10 remoteData.foregroundColor = "#e2e2e2";
The mutate
function helps your Javascript code respond to concurrent updates with versioned control. See the corresponding JavaScript SDK documentation for details.
DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
URI parameters Sid
type: string
The SID of the Document resource to delete. Can be the Document resource's sid
or its unique_name
.
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .documents('ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 syncClient.document("user_prefs").then(function(doc) {
_10 doc.removeDocument().then(function() {
_10 console.log('Document removed.');