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.

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: base/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.