Personalization

Create template

Create a new template.

Jump to examples ↓

POST /api/templates

Security:

Request body:

A single template object.

• Content-Type: application/json

  Template object

  A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

Responses

• 201

  The template was created.

  Response headers:

  • Location string

    The URI for the template, used for later updates or sends.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • ok booleanREQUIRED

      If true, the operation completed successfully and returns an expected response.

    • operation_id string

      A unique string identifying the operation, useful for reporting and troubleshooting.

      Format: uuid

      Example: ef625038-70a3-41f1-826f-57bc11dd625a

    • template_id string

      A unique string identifying the template, used to call the template for pushing and other operations.

      Format: uuid

      Example: 0f7704e9-5dc0-4f7d-9964-e89055701b0a

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "variables": [
        {
            "key": "TITLE",
            "name": "Title",
            "description": "e.g., Mr, Ms, Dr, etc.",
            "default_value": ""
        },
        {
            "key": "FIRST_NAME",
            "name": "First Name",
            "description": "Given name",
            "default_value": null
        },
        {
            "key": "LAST_NAME",
            "name": "Last Name",
            "description": "Family name",
            "default_value": null
        }
    ],
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
        }
    }
}

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateVariable titleVariable = TemplateVariable.newBuilder()
        .setKey("TITLE")
        .setName("Title")
        .setDescription("e.g., Mr, Ms, Dr, etc.")
        .setDefaultValue("")
        .build();

TemplateVariable firstNameVariable = TemplateVariable.newBuilder()
        .setKey("FIRST_NAME")
        .setName("First Name")
        .setDescription("Given name")
        .setDefaultValue(null)
        .build();

TemplateVariable lastNameVariable = TemplateVariable.newBuilder()
        .setKey("LAST_NAME")
        .setName("Last Name")
        .setDescription("Family name")
        .setDefaultValue("")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest()
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .addVariable(titleVariable)
        .addVariable(firstNameVariable)
        .addVariable(lastNameVariable)
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create a new template
template = Template(client)
template.name = 'Welcome Message'
template.description = 'Our welcome message'
template.variables = [
    {
        'key': 'TITLE',
        'name': 'Title',
        'description': 'e.g., Mr., Ms., Dr., etc.',
        'default_value': ''
    },
    {
        'key': 'FIRST_NAME',
        'name': 'First Name',
        'description': 'Given name',
        'default_value': None
    },
    {
        'key': 'LAST_NAME',
        'name': 'Last Name',
        'description': 'Family name',
        'default_value': None
    }
]
template.push = {
    'notification': {
        'alert': 'Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!'
    }
}
response = template.create()
print(f"Template ID: {template.template_id}")  # To get the template ID for future use

# List all templates
for template in TemplateList(client):
    print(
        f"Template ID: {template.template_id}\n"
        f"Created: {template.created_at}\n"
        f"Modified: {template.modified_at}\n"
        f"Last Used: {template.last_used}\n"
        f"Name: {template.name}\n"
        f"Description: {template.description}\n"
        f"Variables: {template.variables}\n"
        f"Push: {template.push}"
    )

# Send a push using a template
push = client.create_push()
push.device_types = ['ios']
push.audience = {
    'ios_channel': 'b8f9b663-0a3b-cf45-587a-be880946e881'
}
push.merge_data = merge_data(
    template_id='ef34a8d9-0ad7-491c-86b0-aea74da15161',
    substitutions={
        'FIRST_NAME': 'Bob',
        'LAST_NAME': 'Smith',
        'TITLE': ''
    }
)
response = push.send()

Delete template

Delete a template. If the template is successfully deleted, the response does not include a body.

Jump to examples ↓

DELETE /api/templates/{template_id}

Security:

Path parameters:

• template_id stringREQUIRED
  A required string ID of the template.

Responses

• 200

  The template with given ID has been successfully deleted.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • ok booleanREQUIRED

      If true, the operation completed successfully and returns an expected response.

    • operation_id string

      A unique string identifying the operation, useful for reporting and troubleshooting.

      Format: uuid

      Example: ef625038-70a3-41f1-826f-57bc11dd625a

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  Response body:

  • Content-Type: application/vnd.urbanairship+json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

DELETE /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateDeleteRequest request = TemplateDeleteRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'

# Delete via template lookup
response = Template(client).lookup(template_id).delete()

# OR, if you want to delete a template without fetching it from the API
response = Template(client).delete(template_id)

List templates

List all existing templates. Returns an array of template objects in the templates attribute.

Jump to examples ↓

GET /api/templates

Security:

Query parameters:

• page integer
  Specifies the desired page number. Defaults to 1.
• page_size integer
  Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
• sort string
  Specifies the name of the field you want to sort results by. Defaults to created_at.

  Possible values:

  • created_at
  • modified_at
  • last_used
• order string
  Specifies the sort order as ascending (asc) or descending (desc). Defaults to asc.

  Possible values:

  • asc
  • desc

Responses

• 200

  Returned on success, with the JSON representation of the templates in the body of the response.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • count integer

      The number of templates in the current response; this is effectively the page size.

    • next_page string

      There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      Format: url

      Example: https://go.urbanairship.com/api/templates?page=2&page_size=1

    • ok booleanREQUIRED

      Success.

    • prev_page string

      Link to the previous page, if available.

      Format: url

    • templates array

      An array of template objects.

    • total_count integer

      The total number of templates.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

GET /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: templates
Count: 1
Total-Count: 1
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "count": 1,
    "total_count": 1,
    "templates": [
        {
            "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "created_at": "2020-08-17T11:10:01Z",
            "modified_at": "2020-08-17T11:10:01Z",
            "last_used": null,
            "name": "Welcome Message",
            "description": "Our welcome message",
            "variables": [
                {
                    "key": "TITLE",
                    "name": "Title",
                    "description": "e.g., Mr, Ms, Dr, etc.",
                    "default_value": ""
                },
                {
                    "key": "FIRST_NAME",
                    "name": "First Name",
                    "description": "Given name",
                    "default_value": null
                },
                {
                    "key": "LAST_NAME",
                    "name": "Last Name",
                    "description": "Family name",
                    "default_value": null
                }
            ],
            "push": {
                "notification": {
                    "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
                }
            }
        }
    ],
    "next_page": null,
    "prev_page": null
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateListingRequest request = TemplateListingRequest.newRequest();
Response<TemplateListingRequest> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all templates
for template in TemplateList(client):
    print(
        f"Template ID: {template.template_id}\n"
        f"Created: {template.created_at}\n"
        f"Modified: {template.modified_at}\n"
        f"Last Used: {template.last_used}\n"
        f"Name: {template.name}\n"
        f"Description: {template.description}\n"
        f"Variables: {template.variables}\n"
        f"Push: {template.push}"
    )

Look up a template

Fetch the current definition of a single template.

Jump to examples ↓

GET /api/templates/{template_id}

Security:

Path parameters:

• template_id stringREQUIRED
  A required string ID of the template.

Responses

• 200

  Returned on success, with the JSON representation of the template in the body of the response.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • ok booleanREQUIRED

      If true, the operation completed successfully and returns an expected response.

    • template object<Template object>

      A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  Response body:

  • Content-Type: application/vnd.urbanairship+json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

GET /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: template
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "template": {
        "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "created_at": "2020-08-17T11:10:02Z",
        "modified_at": "2020-08-17T11:10:02Z",
        "last_used": null,
        "name": "Welcome Message",
        "description": "Our welcome message",
        "variables": [
            {
                "key": "TITLE",
                "name": "Title",
                "description": "e.g., Mr, Ms, Dr, etc.",
                "default_value": ""
            },
            {
                "key": "FIRST_NAME",
                "name": "First Name",
                "description": "Given name",
                "default_value": null
            },
            {
                "key": "LAST_NAME",
                "name": "Last Name",
                "description": "Family name",
                "default_value": null
            }
        ],
        "push": {
            "notification": {
                "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
            }
        }
    }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateListingRequest request = TemplateListingRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateListingResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
template = Template(client).lookup(template_id)
print(
    template.template_id, template.created_at, template.modified_at,
    template.last_used, template.name, template.description,
    template.variables, template.push
)

Push to template

Send a push notification based on a template to a list of devices. The body of the request must be a single push template payload or an array of one or more push template payloads.

Jump to examples ↓

POST /api/templates/push

Security:

Request body:

A single push template payload or an array of push template payloads. Provide an override with any variable that has a null default value. For example, if you created a template with the variable FIRST_NAME, and that variable has null as a default value, you must provide a substitution for FIRST_NAME when pushing to that template.

• Content-Type: application/json

  One of
  • Push template payload

    A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

  • Array of push templates array<Push Template Payload>

    A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

Responses

• 202

  The push notification has been accepted for processing.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • ok booleanREQUIRED

      If true, the operation completed successfully and returns an expected response.

    • operation_id string

      A unique string identifying the operation, useful for reporting and troubleshooting.

      Format: uuid

      Example: ef625038-70a3-41f1-826f-57bc11dd625a

    • push_ids array[string]

      An array of the push IDs for this operation.

      Min items: 1, Max items: 100

      Example: [00256e0b-b02f-4f12-a77f-4c3d57078330 f59970d3-3d42-4584-907e-f5c57f5d46a1]

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "device_types": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}

HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplatePushPayload payload = TemplatePushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Smith")
                .addSubstitution("TITLE", "Mr.")
                .build())
        .build();

TemplatePushRequest request = TemplatePushRequest.newRequest()
        .addTemplatePushPayload(payload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Send a push using a template
push = client.create_push()
push.device_types = ['ios']
push.audience = {
    'ios_channel': 'b8f9b663-0a3b-cf45-587a-be880946e881'
}
push.merge_data = merge_data(
    template_id='ef34a8d9-0ad7-491c-86b0-aea74da15161',
    substitutions={
        'FIRST_NAME': 'Bob',
        'LAST_NAME': 'Smith',
        'TITLE': ''
    }
)
response = push.send()

Schedule a templated push

Schedule a push notification based on a template to a list of devices. Like a standard template-based push, the body of the request includes one or more push template payloads along with a schedule object determining when the template-based push should be sent.

Jump to examples ↓

POST /api/templates/schedules

Security:

Request body:

An array of scheduled pushes.

• Content-Type: application/json

  array<object>
  ARRAY ITEM

  • A scheduled push template object defines a push by overriding the variables defined in a specific template object and the schedule determining when the push should be sent. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

    OBJECT PROPERTIES
    • audience object<Audience Selector1000>REQUIRED
      The audience for the template.
    • campaigns object<Campaigns Object>
    • device_types array[string]REQUIRED
      An array containing one or more strings identifying targeted platforms.
    • merge_data objectREQUIRED
      A template selector describing the template ID and variable substitutions to use with it.
    • name string
      An optional name for the scheduled push operation.
    • schedule object<Schedule Spec>REQUIRED
      Determines when the push is sent.

Responses

• 202

  The scheduled push has been accepted for processing.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • ok booleanREQUIRED

      Success.

    • operation_id string

      A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs.

      Format: uuid

      Example: ef625038-70a3-41f1-826f-57bc11dd625a

    • schedule_ids array[string]

      An array of schedule IDs.

      Min items: 1, Max items: 100

      Example: [00256e0b-b02f-4f12-a77f-4c3d57078330 f59970d3-3d42-4584-907e-f5c57f5d46a1]

    • schedule_urls array[string]

      An array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the schedule_id of the schedule.

      Max items: 100

      Example: [https://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109]

    • schedules array

      An array of schedule objects.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/templates/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
    {
        "name": "Hello Bob",
        "schedule": {
           "scheduled_time": "2020-05-02T22:00:00Z"
        },
        "device_types": [ "ios" ],
        "audience": {
           "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Bob",
                "LAST_NAME": "Takahashi",
                "TITLE": null
            }
        }
    },
    {
        "name": "Hello Joe",
        "schedule": {
           "scheduled_time": "2020-05-05T18:00:00Z"
        },
        "device_types": [ "android" ],
        "audience": {
           "android_channel": "df6a6b50-9843-0304-d5a5-743f246a4946"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Joe",
                "LAST_NAME": "Smith",
                "TITLE": "Sir"
            }
        }
    }
]

HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "efb18e92-9a60-6689-45c2-82fedab36399",
    "schedule_urls" : [
        "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
        "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
    ],
    "schedule_ids" : [
        "a0cef4f9-1fcd-47ef-b459-01f432b64043",
        "fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
    ],
    "schedules" : [
        {
            "url" : "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
            "name": "Hello Joe",
            "schedule" : { "..." },
            "push" : { "..." },
            "push_ids": [ "6a5ecb9c-46ee-4af4-9ced-9308121afaf9" ]
        },
        {
            "url" : "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf",
            "name": "Hello Bob",
            "schedule" : { "..." },
            "push" : { "..." },
            "push_ids": [ "5162bbf8-7de7-4040-a64d-e018b71f02f6" ]
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateScheduledPushPayload payload = TemplateScheduledPushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Takahashi")
                .addSubstitution("TITLE", "Dr.")
                .build())
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-05-05T18:00:00Z"))
                .build())
        .build();

TemplateScheduledPushRequest request = TemplateScheduledPushRequest.newRequest()
                                          .addTemplateScheduledPushPayload(payload);
Response<ScheduleResponse> response = client.execute(request);

Update template

Update a template. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.

Jump to examples ↓

POST /api/templates/{template_id}

Security:

Path parameters:

• template_id stringREQUIRED
  A required string ID of the template.

Request body:

• Content-Type: application/json

  A partially-defined template object. Provide only variables and push items that you want to update.

  OBJECT PROPERTIES
  • description string

    The description of the template.

  • name stringREQUIRED

    The name of the template.

  • push object<Template push object>

    A partial push object describing everything about a push notification, except for the audience and device_types keys (which are defined in the Push template payload) and the message key (which is incompatible with templates).

  • variables array

    An array of variable specifications.

Responses

• 200

  Returned if the template has been successfully updated.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OBJECT PROPERTIES
    • ok booleanREQUIRED

      If true, the operation completed successfully and returns an expected response.

    • operation_id string

      A unique string identifying the operation, useful for reporting and troubleshooting.

      Format: uuid

      Example: ef625038-70a3-41f1-826f-57bc11dd625a

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161")
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = Template(client)
updated_template.push = {
    'notification': {
        'alert': 'Hi {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update(template_id)

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = Template(client).lookup(template_id)
updated_template.push = {
    'notification': {
        'alert': 'Greetings {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update()

Validate a template

This endpoint accepts the same range of payloads as /api/template/push, but only parses and validates the payload. It does not actually send a push.

Jump to examples ↓

POST /api/templates/push/validate

Security:

Request body:

A single push template payload or an array of push template payloads.

• Content-Type: application/json

  One of
  • Push template payload

    A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

  • array<Push Template Payload>

    A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

Responses

• 200

  The payload was valid.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OK response

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/templates/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "device_types": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}

HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplatePushPayload payload = TemplatePushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Smith")
                .addSubstitution("TITLE", "Mr.")
                .build())
        .build();

TemplatePushRequest request = TemplatePushRequest.newRequest()
        .addTemplatePushPayload(payload)
        .setValidateOnly(true);

Response<TemplateResponse> response = client.execute(request);