Remote Content

Several API calls, notably send_message, create_scheduled_event, and create_scheduled_events, support remote content features to compose an API call out of one or more remote documents that are fetched when needed.

For example, a send_message JSON document might look like this:

{
  "arguments": {
    "recipients": [ "first@example.com", "second@example.com" ],
    "content": {
      "text/html": "<b>Welcome to the example!</b>"
    }
  }
}

This could be broken up into severap parts that are fetched remotely:

{
  "arguments": {
    "recipients": {
      "$ref": "https://example.com/integration/recipients.json"
    },
    "content": {
      "$ref": "https://example.com/integration/content.json"
    }
  }
}

Where https://example.com/integration/recipients.json returns a document of the form:

[ "first@example.com", "second@example.com" ]

And https://example.com/integration/content.json returns the corresponding content:

{
  "text/html": "<b>Welcome to the example!</b>"
}

This will be reconstructed into a JSON document identical to the original.

Separating certain components from the API can help to reduce the API call size, and can be important when making scheduled calls where the content will change depending on when the call is invoked.

Element Substitution

Each branch of a JSON document with a "$ref" key is interpreted as dynamic content and is fetched and substituted in-place. The fetched document does not necessarily have to be the same structure, and can instead be any valid JSON, even an array or just a string, number, or boolean value.

Additional Content Types

In addition to JSON, YAML and CSV content can be included as well provided these are identified with the $type parameter.

{
  "arguments": {
    "recipients": {
      "$ref": "https://example.com/integration/recipients.csv",
      "$type": "application/csv"
    },
    "content": {
      "$ref": "https://example.com/integration/content.yml",
      "$type": "application/yaml"
    }
  }
}

Using GET vs. POST

The default retrieval method is HTTP GET, but this can be changed to POST using the $method key:

{
  "arguments": {
    "recipients": {
      "$ref": "https://example.com/integration/recipients",
      "$method": "post"
    }
  }
}

This can also include other data if necessary, such as might be required for authentication:

{
  "arguments": {
    "recipients": {
      "$ref": "https://example.com/integration/recipients",
      "$method": "post",
      "$data": {
        "secret_key": "__SECRET_KEY__"
      }
    }
  }
}

The values in $data are encoded using conventional HTTP “form encoding” (application/x-www-form-urlencoded) and passed in as the request body.