Personalization

Use the /templates API to create templates and push templatized notifications.

Note

Consider the /templates API deprecated. You should instead create templates in the Airship dashboard and send using the /create-and-send or /pipelines APIs.

Create template

Create a new template.

Jump to examples ↓

POST /api/templates

Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

basicAuth

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.
  - template_id string
    A unique string identifying the template, used to call the template for pushing and other operations.
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}

Note

Security:

basicAuth

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.
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

Note

Security:

basicAuth

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.
  - ok booleanREQUIRED
    Success.
  - prev_page string
    Link to the previous page, if available.
  - 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}

Note

Security:

basicAuth

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

Note

Security:

basicAuth
oauth2Token : psh

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.
  - push_ids array[string]
    An array of the push IDs for this operation.
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:

basicAuth
oauth2Token : psh

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.
  - schedule_ids array[string]
    An array of schedule IDs.
  - 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.
  - 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}

Note

Security:

basicAuth

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

basicAuth
oauth2Token : psh

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);