--- title: "Edit a WhatsApp Template with OAuth 2.0" slug: "edit-a-whatsapp-template-with-oauth-2-0" description: "Covers editing WhatsApp templates using the Insider One API with OAuth 2.0, including required scopes, edit rules, request parameters, errors, and limits." updated: 2026-11-18T09:50:43Z published: 2026-11-18T09:50:43Z canonical: "academy.insiderone.com/edit-a-whatsapp-template-with-oauth-2-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://academy.insiderone.com/llms.txt > Use this file to discover all available pages before exploring further. # Edit a WhatsApp Template with OAuth 2.0 You can use the WhatsApp Template Management API to edit an existing managed WhatsApp template in Insider One. Use this API version when you authenticate requests with OAuth 2.0. Editing a template through the API lets you update its content without recreating it, so the template keeps its Insider One template ID. This page covers the endpoint, the required scope, the parameters, the rules that decide which edits are accepted, and the errors you can handle in your integration. > [!NOTE] > All examples on this page use sample data and payloads for documentation purposes only. Before you go live, replace all template names, languages, components, client credentials, and media handles with values specific to your own integration. > [!NOTE] > **Field naming rule:** The token request uses **snake_case** fields, such as `client_id` and `client_secret`. Template request bodies use **camelCase** fields, such as `name`, `language`, `category`, and `components`. > [!WARNING] > Edit requests need the `wa-temp-update` scope. This scope is separate from the other template scopes and applies only to the `PUT` method. > [!WARNING] > The `wa-temp-manage` scope covers only `POST` requests, such as creating and restoring a template. The gateway refuses an edit call that uses an existing token without the `wa-temp-update` scope. Add the new scope to your current credential, or generate a new credential that includes it. ## Endpoint and Headers > **PUT** https://gw.useinsider.com/api/wa/v2/templates/42 | Header | Required | Description | | --- | --- | --- | | Authorization | Yes | Your OAuth 2.0 token in the format `Bearer your-oauth2-token`. The token must include the `wa-temp-update` scope. | | Content-Type | Yes | `application/json` | ## Path Parameter | Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | Integer | Yes | The Insider One template ID. It is the same ID that the List and Get endpoints return. | ## Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | components | Array[object] | Yes | The full component list you want the template to have. You must send at least one component. Send the complete list, not a partial one. | | name | String | No | The current template name. If you send it, the value must match the current name exactly. You cannot change the template name. | | language | String | No | The current template language. If you send it, the value must match the current language exactly. You cannot change the template language. | | category | String | No | The template category. You can change it only when the template is not in APPROVED status. A category change counts as a structural edit. | | bid_spec | N/A | No | Not accepted on this endpoint. You cannot change the max price of an existing template. | The endpoint rejects any other top-level field, including `ttl`, with a `400` status. ## Which templates you can edit You can edit only templates in APPROVED, PAUSED, or REJECTED status. The endpoint refuses every other status, including PENDING and IN-REVIEW. Edit limits apply to APPROVED templates: - You can edit an APPROVED template once every 24 hours. - You can edit an APPROVED template 10 times in 30 days. - The limits are counted per template, and edits made in Meta’s WhatsApp Manager count toward the same limits. - PAUSED and REJECTED templates do not count toward the limits. Edits fall into two types: - **Text-only edit:** changes only the header, body, or footer text, or the button labels. Insider One always accepts a text-only edit. - **Structural edit:** any other change, including a category change. The endpoint refuses a structural edit while an active, running, or scheduled campaign or journey uses the template. You cannot edit an ARCHIVED template. Restore the template first, then edit it. > [!NOTE] > To restore an archived template, refer to [Restore an Archived WhatsApp Template with OAuth 2.0](https://academy.insiderone.com/docs/restore-an-archived-whatsapp-template-with-oauth-2-0). ## Sample Request First, generate an OAuth 2.0 token. Include the `wa-temp-update` scope in the request: ```bash curl --location 'https://gw.useinsider.com/auth/token' \ --header 'Content-Type: application/json' \ --data '{  "client_id": "your-client-id",  "client_secret": "your-client-secret",  "scopes": ["wa-temp-read", "wa-temp-manage", "wa-temp-update", "wa-temp-delete"] }' ``` Then, send the edit request with the token: ```bash curl --location --request PUT 'https://gw.useinsider.com/api/wa/v2/templates/42' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer your-oauth2-token' \ --data '{  "components": [    {      "type": "BODY",      "text": "Hi {{1}}, your order {{2}} has shipped.",      "example": { "body_text": [["Jane", "A-100"]] }    }  ] }' ``` ## Sample Response #### 200 OK ```json { "message": "template update accepted" } ``` > [!NOTE] > A successful response means Meta received the edit, not that Meta approved it. The template moves to IN-REVIEW status and you cannot edit it again until Meta answers. To track the result, use the Get WhatsApp Template Details endpoint. ## Sample Error Responses Every failure returns a `message` field. Edit-specific failures also return an `error` object with a `key` value that you can use to branch your logic. Retryable failures include a `Retry-After` header. The gateway returns `401` when the client credentials are invalid, or when the bearer token is missing, expired, or malformed. It returns `403` when the token does not include the `wa-temp-update` scope. The gateway sets these two responses, so they have no edit-specific `error.key`. | Status | Case | message | error.key | | --- | --- | --- | --- | | 401 | Invalid client credentials, or missing, expired, or malformed bearer token | Set by the gateway | N/A | | 403 | Token does not include the wa-temp-update scope | Set by the gateway | N/A | | 400 | Invalid template ID in the path | template id is invalid | N/A | | 400 | Invalid JSON body or unknown field | failed to decode request | N/A | | 400 | Missing components | failed to validate request | Validator text | | 400 | Status does not support editing | template status does not support editing | template-edit-status-not-supported | | 400 | Immutable field sent (name, language, category, or bid_spec) | For example, approved template category cannot be changed | template-edit-immutable-field | | 404 | Template missing, template not owned by the account, or editing not enabled for the account | template not found | N/A | | 409 | Template in active use and the edit is structural | template is in active use and the edit changes its structure | template-edit-structural-blocked | | 422 | Content rejected | template content was rejected by content validation | template-edit-content-shield-rejected | | 422 | Router domain missing for URL buttons | active whatsapp router domain not found | N/A | | 429 | Edit limit reached | approved template edit 24-hour limit reached, or approved template edit 30-day limit reached | template-edit-quota-exceeded | | 503 | Temporary failure, retry the same request | template edit quota is temporarily unavailable, or template edit dependency unavailable | template-edit-quota-unavailable, template-edit-usage-unavailable | | Meta’s status code | Meta rejects the edit (Meta’s message is returned as is) | For example, Invalid parameter | template-edit-meta-rejected | | 502 | Result unknown, or accepted by Meta but not stored locally | template edit result is unknown, or template edit accepted by Meta but local persistence failed | template-edit-meta-rejected, template-edit-local-persist-failed | #### 400 Bad Request: invalid template ID ```json {  "message": "template id is invalid" } ``` #### 400 Bad Request: invalid JSON body or unknown field ```json {  "message": "failed to decode request" } ``` #### 400 Bad Request: missing components The response also includes the validator text that describes the failed rule. ```json {  "message": "failed to validate request" } ``` #### 400 Bad Request: status does not support editing ```json {  "message": "template status does not support editing",  "error": {    "key": "template-edit-status-not-supported"  } } ``` #### 400 Bad Request: immutable field The message names the field that you cannot change. ```json {  "message": "approved template category cannot be changed",  "error": {    "key": "template-edit-immutable-field"  } } ``` #### 404 Not Found ```json {  "message": "template not found" } ``` #### 409 Conflict To resolve this error, send a text-only edit, or wait until no active, running, or scheduled campaign or journey uses the template. ```json {  "message": "template is in active use and the edit changes its structure",  "error": {    "key": "template-edit-structural-blocked"  } } ``` #### 422 Unprocessable Entity: content rejected ```json {  "message": "template content was rejected by content validation",  "error": {    "key": "template-edit-content-shield-rejected"  } } ``` #### 422 Unprocessable Entity: router domain missing This error occurs when the template has URL buttons and the account has no active WhatsApp router domain. Contact the Insider team to resolve it. ```json {  "message": "active whatsapp router domain not found" } ``` #### 429 Too Many Requests: 24-hour edit limit ```json {  "message": "approved template edit 24-hour limit reached",  "error": {    "key": "template-edit-quota-exceeded"  } } ``` #### 429 Too Many Requests: 30-day edit limit ```json {  "message": "approved template edit 30-day limit reached",  "error": {    "key": "template-edit-quota-exceeded"  } } ``` #### 503 Service Unavailable: quota check unavailable The response includes a Retry-After header. You can retry the same request after the wait time it gives. ```json {  "message": "template edit quota is temporarily unavailable",  "error": {    "key": "template-edit-quota-unavailable"  } } ``` #### 503 Service Unavailable: dependency unavailable The response includes a Retry-After header. You can retry the same request after the wait time it gives. ```json {  "message": "template edit dependency unavailable",  "error": {    "key": "template-edit-usage-unavailable"  } } ``` #### Meta’s status code: edit rejected by Meta Insider One returns Meta’s status code and message as is. ```json {  "message": "Invalid parameter",  "error": {    "key": "template-edit-meta-rejected"  } } ``` #### 502 Bad Gateway: result unknown ```json {  "message": "template edit result is unknown",  "error": {    "key": "template-edit-meta-rejected"  } } ``` #### 502 Bad Gateway: accepted by Meta but not stored locally ```json {  "message": "template edit accepted by Meta but local persistence failed",  "error": {    "key": "template-edit-local-persist-failed"  } } ``` > [!WARNING] > Do not retry a 502 response automatically. The edit might already be live at Meta, so check the template with the [Get WhatsApp Template Details](/v1/docs/get-whatsapp-template-details-with-oauth-2-0) endpoint first. ## Limitations - The rate limit is **10 requests per second** per account. - The endpoint sends **one request** to Meta and never retries it. - The API does not ask for confirmation before making a text-only edit to a template in use. It applies the edit.