Metadata¶

Metadata can be supplied with API methods where appropriate. It is returned in callbacks and data provision, making it easier to track activity within the DIY Surveys platform.

Warning

The API 3.2 OpenAPI MessageModel does not currently expose MetaData or per-request Callback fields. The message examples on this page therefore describe the API 3.0 contract. Use the Scalar reference as the source of truth for a 3.2 integration.

Metadata is a JSON array and can contain any number of entries:

[
  { "RequestID": "1234567890DEFED" },
  { "OrgID": 1010 },
  { "Instance": "ETRERT" },
  { "Campaign": 1242 },
  { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
]

Values can be strings, numbers, or dates.

Supplying metadata when sending a message¶

URL: https://api.diysurveys.com/api/v3.0/Message/Send
Header:
Authorization: Basic ABCDEFG
Method: POST
Content:

{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "message",
  "Reply": true,
  "When": "2020-02-04T11:47:33.645773+00:00",
  "Window": [{ "From": "09:00", "To": "16:00", "Days": "1,2,3,4,5" }],
  "Callback": "https://yourco.com/api/messagetracker",
  "MetaData": [
    { "RequestID": "1234567890DEFED" },
    { "OrgID": 1010 },
    { "Instance": "ETRERT" },
    { "Campaign": 1242 },
    { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
  ]
}

Using metadata in message construction¶

Metadata values can be used in message construction.

{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "Hi {name}, Please could you complete this survey {url}",
  "Reply": true,
  "When": "2020-02-04T11:47:33.645773+00:00",
  "Window": [{ "From": "09:00", "To": "16:00", "Days": "1,2,3,4,5" }],
  "Callback": "https://yourco.com/api/messagetracker",
  "MetaData": [
    { "name": "David" },
    { "url": "https://diysurveys.com" },
    { "Instance": "ETRERT" },
    { "Campaign": 1242 },
    { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
  ]
}

Callbacks¶

When a callback is triggered, additional metadata is provided along with the standard callback information.

URL: https://yourco.com/api/messagetracker
Header:
Authorization: Basic ABCDEFG
Method: POST
Content:

{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "the response",
  "When": "2020-02-04T11:47:33.645773+00:00",
  "MessageID": "MS1312312312323",
  "MetaData": [
    { "RequestID": "1234567890DEFED" },
    { "OrgID": 1010 },
    { "Instance": "ETRERT" },
    { "Campaign": 1242 },
    { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
  ]
}

Key metadata values¶

Most metadata values are not interpreted by the DIY Surveys platform. Some values have platform-specific meaning:

Value	Description
`Campaign`	Used in the keyword process to match recipient messages to specific keywords for STOP, HELP, and INFO.
`Country`	Used as a prefix to the destination value in a message when numbers do not include a country-code prefix.

Access token metadata values¶

Default metadata can be configured on an access token. Metadata supplied with individual calls is then merged with default metadata. Avoid conflicting values.