# Personalization Use the `/templates` API to create templates and push templatized notifications. {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} ## Create template {#createtemplate} Create a new template. [Jump to examples ↓](#createtemplate-examples) ### `POST /api/templates` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) **Request body** A single template object. **Content-Type:** `application/json` [Template object]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templateobject) **Responses** **`201`** The template was created. Response headers: | Name | Type | Description | |------|------|-------------| | `Location` | `string` | The URI for the template, used for later updates or sends. | Response body: **Content-Type:** `application/vnd.urbanairship+json; version=3` - **`ok`** `boolean` **REQUIRED** 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/templates HTTP/1.1 Authorization: Basic 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 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" } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .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 response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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 {#deletetemplate} Delete a template. If the template is successfully deleted, the response does not include a body. [Jump to examples ↓](#deletetemplate-examples) ### `DELETE /api/templates/{template_id}` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `template_id` | `string` | Required | 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` - **`ok`** `boolean` **REQUIRED** 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`404`** The requested resource doesn't exist. Response body: **Content-Type:** `application/vnd.urbanairship+json` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http DELETE /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 ``` ```http HTTP/1.1 200 OK Content-Type: application/vnd.urbanairship+json; version=3 { "ok": true, "operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a" } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .build(); TemplateDeleteRequest request = TemplateDeleteRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161"); Response response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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 {#gettemplates} List all existing templates. Returns an array of template objects in the `templates` attribute. [Jump to examples ↓](#gettemplates-examples) ### `GET /api/templates` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `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` - **`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`** `boolean` **REQUIRED** Success. - **`prev_page`** `string` Link to the previous page, if available. Format: `url` - **`templates`** `array` <[Template object]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templateobject)> 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http GET /api/templates HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 ``` ```http 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 } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .build(); TemplateListingRequest request = TemplateListingRequest.newRequest(); Response response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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 {#gettemplate} Fetch the current definition of a single template. [Jump to examples ↓](#gettemplate-examples) ### `GET /api/templates/{template_id}` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `template_id` | `string` | Required | 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` - **`ok`** `boolean` **REQUIRED** If true, the operation completed successfully and returns an expected response. - **`template`** `object` <[Template object]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templateobject)> 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`404`** The requested resource doesn't exist. Response body: **Content-Type:** `application/vnd.urbanairship+json` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http GET /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 ``` ```http 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!" } } } } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .build(); TemplateListingRequest request = TemplateListingRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161"); Response response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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 {#pushtotemplate} 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 ↓](#pushtotemplate-examples) ### `POST /api/templates/push` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) - [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-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]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#pushtemplatepayload) 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` **Responses** **`202`** The push notification has been accepted for processing. Response body: **Content-Type:** `application/vnd.urbanairship+json; version=3` - **`ok`** `boolean` **REQUIRED** 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/templates/push HTTP/1.1 Authorization: Basic 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 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" ] } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .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 response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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 {#scheduletemplatedpush} 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 ↓](#scheduletemplatedpush-examples) ### `POST /api/templates/schedules` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) - [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): psh **Request body** An array of scheduled pushes. **Content-Type:** `application/json` Type: `array` **Responses** **`202`** The scheduled push has been accepted for processing. Response body: **Content-Type:** `application/vnd.urbanairship+json; version=3` - **`ok`** `boolean` **REQUIRED** 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. Min items: 0, Max items: 100 Example: `https://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109` - **`schedules`** `array` <[Schedule object]({{< ref "/developer/rest-api/ua/schemas/schedules/" >}}#scheduleobject)> 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/templates/schedules HTTP/1.1 Authorization: Basic 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 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" ] } ] } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .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 response = client.execute(request); ``` --- ## Update template {#updatetemplate} 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 ↓](#updatetemplate-examples) ### `POST /api/templates/{template_id}` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `template_id` | `string` | Required | A required string ID of the template. | **Request body** **Content-Type:** `application/json` - **`description`** `string` The description of the template. - **`name`** `string` **REQUIRED** The name of the template. - **`push`** `object` <[Template push object]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templatepushobject)> 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](/docs/developer/rest-api/ua/schemas/personalization-template-objects/#pushtemplatepayload)) and the `message` key (which is incompatible with templates). - **`variables`** `array` <[Template variables]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templatevariableobject)> 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` - **`ok`** `boolean` **REQUIRED** 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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1 Authorization: Basic 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 HTTP/1.1 200 OK Content-Type: application/vnd.urbanairship+json; version=3 { "ok": true, "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946" } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .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 response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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) ``` *Alternatively, call the lookup function on your updated template:* ```python from urbanairship import ( BasicAuthClient, Template, TemplateList, merge_data ) client = BasicAuthClient( key='', 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 {#validatetemplate} 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 ↓](#validatetemplate-examples) ### `POST /api/templates/push/validate` {{< note >}} The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/docs/guides/personalization/content/templates/) or use the [Content API](/docs/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/docs/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/docs/developer/rest-api/ua/operations/automation/) APIs. {{< /note >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) - [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-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]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#pushtemplatepayload) 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` **Responses** **`200`** The payload was valid. Response body: **Content-Type:** `application/vnd.urbanairship+json; version=3` [OK response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#okresponseobject) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/templates/push/validate HTTP/1.1 Authorization: Basic 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 HTTP/1.1 200 OK Content-Length: 123 Data-Attribute: push_ids Content-Type: application/vnd.urbanairship+json; version=3 { "ok" : true } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .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 response = client.execute(request); ``` ---