Edit WhatsApp Templates 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.

Edit requests need the wa-temp-update scope. This scope is separate from the other template scopes and applies only to the PUT method.

The wa-temp-manage scope covers only POST requests, so 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

Path parameter

Body parameters

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.

Sample request

First, generate an OAuth 2.0 token. Include the wa-temp-update scope in the request:

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:

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

{ "message": "template update accepted" }

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.

400 Bad Request: invalid template ID

{
  "message": "template id is invalid"
}

400 Bad Request: invalid JSON body or unknown field

{
  "message": "failed to decode request"
}

400 Bad Request: missing components

The response also includes the validator text that describes the failed rule.

{
  "message": "failed to validate request"
}

400 Bad Request: status does not support editing

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

{
  "message": "approved template category cannot be changed",
  "error": {
    "key": "template-edit-immutable-field"
  }
}

404 Not Found

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

{
  "message": "template is in active use and the edit changes its structure",
  "error": {
    "key": "template-edit-structural-blocked"
  }
}

422 Unprocessable Entity: content rejected

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

{
  "message": "active whatsapp router domain not found"
}

429 Too Many Requests: 24-hour edit limit

{
  "message": "approved template edit 24-hour limit reached",
  "error": {
    "key": "template-edit-quota-exceeded"
  }
}

429 Too Many Requests: 30-day edit limit

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

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

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

{
  "message": "Invalid parameter",
  "error": {
    "key": "template-edit-meta-rejected"
  }
}

502 Bad Gateway: result unknown

{
  "message": "template edit result is unknown",
  "error": {
    "key": "template-edit-meta-rejected"
  }
}

502 Bad Gateway: accepted by Meta but not stored locally

{
  "message": "template edit accepted by Meta but local persistence failed",
  "error": {
    "key": "template-edit-local-persist-failed"
  }
}

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.