Custom Events

Use the Custom Events GraphQL API to send user actions to use in the Attentive Segment Builder and Journey Builder for both email and text messages. This data cannot contain any sensitive or special categories of information as defined in applicable data protection and privacy laws, including the California Consumer Privacy Act (CCPA) and California Privacy Rights Act (CPRA). See a list of specific categories of data you cannot share with Attentive here.

Create Custom Event

Use the createCustomEvent mutation for any event-based data representing user actions.

The following input fields are provided:

Name Description
type Required. The type of event. This name is case sensitive. "Order shipped" and "Order Shipped" would be considered different event types.
user Required. User associated with the action. Note that this is a visitor to the site and does not need to be actively subscribed to Attentive.
properties Optional. Any metadata associated with the event.

Object keys are expected to be strings, and cannot contain any of the following special characters:

  • double quote "
  • curly braces { }
  • square brackets [ ]
  • backslash \
  • vertical bar |

Object values can be any type. Note that both object keys and object values are case sensitive. For example, "deliverydate" and "DeliveryDate" would be considered different event properties.

Name Description
mediaUrl Optional. URL of the image that accompanies MMS. Be sure to add a dynamic product image in the message composer in the Attentive UI when adding a text message step to a journey triggered by the custom event.
externalEventId Optional. A unique identifier representing this specific event. A UUID is recommended.
occurredAt Optional. Timestamp of when the action occurred in ISO 8601 format. If the timestamp is older than 12 hours, it will not trigger any relevant Journeys. If no timestamp is provided, it is assumed the event occurred when the endpoint is called.

Notes:

  • When you’re creating journeys that use custom events data, you can only use lists and nested objects with email messages. Lists and nested objects are not currently supported for SMS.
  • For URLs that are provided as a value, Attentive will automatically shorten the link with your brand's link shortener. For example, https://mysite.com/. Note that Attentive can only shorten URLs that are 1,024 characters or fewer.

Example Mutation

Make sure to set the Authorization: Bearer <Unique API Key> on the request. For more information about obtaining a unique API Key please see the Authentication Docs

POST https://api.attentivemobile.com/v1/graphql

Copy
Copied
mutation createCustom($customEventInput: CreateCustomEventInput!) {
  createCustomEvent(input: $customEventInput) {
    externalEventId
    occurredAt
    properties
    type
    user {
      email
      phone
      externalIdentifiers {
        clientUserId
        customIdentifiers {
          name
          value
        }
      }
    }
  }
}

Example Input Variable

Copy
Copied
{
    "customEventInput": {
        "externalEventId": "37fb97a9-6cfd-4983-bd65-68d104d53b70",
        "occurredAt": "2021-03-30T14:38:29+00:00",
        "properties": "{ \"customKey\":\"customValue\" }",
        "type": "Order Shipped",
        "user": {
            "email": "test@gmail.com",
            "phone": "+13115552368",
            "externalIdentifiers": {
                "clientUserId": "c60b3f4e-ec73-4ff0-be4b-6a0fce825e89",
                "customIdentifiers": [
                    {
                        "name": "customIdentifierName",
                        "value": "customIdentifierValue"
                    }
                ]
            }
        }
    }
}

Example Response

Copy
Copied
{
    "data": {
        "createCustomEvent": {
            "externalEventId": "37fb97a9-6cfd-4983-bd65-68d104d53b70",
            "occurredAt": "2021-03-30T14:38:29Z",
            "properties": "{ \"customKey\":\"customValue\" }",
            "type": "Order Shipped",
            "user": {
                "email": "test@gmail.com",
                "phone": "+13115552368",
                "externalIdentifiers": {
                    "clientUserId": "c60b3f4e-ec73-4ff0-be4b-6a0fce825e89",
                    "customIdentifiers": [
                        {
                            "name": "customIdentifierName",
                            "value": "customIdentifierValue"
                        }
                    ]
                }
            }
        }
    },
    "extensions": {
        "traceId": "00000"
    }
}