💬 Командный WhatsApp-Инбокс на новой ПлатформеЕщё
1msg official logo

Return and refund update via WhatsApp API

The scenario sends the customer a personalized WhatsApp template when an order return is registered or updated.

Use case overview

The scenario sends the customer a personalized WhatsApp template when an order return is registered or updated. The message includes the customer name, order number, product name, and return or refund next step. A static URL button opens return details or label download.

Template example

Hello, {{1}}! A return has been initiated for order #{{2}} for "{{3}}". {{4}}.

Return details
  • {{1}}
    customer name
  • {{2}}
    order number
  • {{3}}
    product name
  • {{4}}
    return status, refund timeline, or drop-off instruction
  • “Return details”
    button — fixed in the Meta template
WhatsApp Business API for order return notification

When to use it

Reach for this when the OMS or returns portal registers or updates a return and the customer needs a proactive status update on a channel they actually check — often with no open WhatsApp conversation, so only an approved template can go out first. It fits e-commerce return flows, marketplaces fielding return-status questions, and integrators wiring returns-portal webhooks into WhatsApp outbound.

Fewer "where is my refund?" contacts
Customer name, order number, product name and the return or refund next step arrive as four body variables in WhatsApp, so the client has a searchable update instead of opening a support ticket.
Fewer chargeback disputes
Variable four carries the refund timeline or drop-off instruction at the moment the return is registered, giving the customer a written record in chat before they dispute the charge.
No manual return-status messages
The returns system fires the template when it registers or updates a return, so staff do not retype order details or send one-off emails.
Return details one tap away
The static Return details URL button is fixed in the Meta template — the customer opens label download or return instructions from chat without asking support for the link.
Logged delivery for finance follow-up
Delivery result is logged after send, so the e-commerce platform or CRM has a record tied to the return event for finance or support follow-up.

Workflow

  1. Trigger

    The returns system registers or updates a return and fires an event.

    event · triggered

  2. Capture event

    The system resolves the customer phone number and return fields.

    phone: "+…"

  3. Build & send

    A personalized template message is built with four body variables and a static URL button.

    POST /sendTemplate

  4. Delivered

    The customer receives the WhatsApp update and can open return details via the button.

    delivered

  5. Status tracked

    Delivery result is logged; errors are handled according to platform rules.

    status: "read"

WhatsApp Business API for order return notification

Technical implementation

Prerequisites

  1. 1MSG API Key · How to get API Key
  2. WhatsApp Business account · How to Connect WABA
  3. WhatsApp Template · How to Approve WABA Template
  4. Customer opt-in · How to Manage Customers Consent

Code examples

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===

API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_CUSTOMERNAME="___"         # {{1}} customer name
TEST_TICKETNUMBER="___"         # {{2}} ticket number
TEST_PRODUCTNAME="___"         # {{3}} product name
TEST_NEXTSTEP="___"         # {{4}} next step

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
            "TEST_TICKETNUMBER=$TEST_TICKETNUMBER" \
            "TEST_PRODUCTNAME=$TEST_PRODUCTNAME" \
            "TEST_NEXTSTEP=$TEST_NEXTSTEP"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} customer name → ${TEST_CUSTOMERNAME}
# {{2}} ticket number → ${TEST_TICKETNUMBER}
# {{3}} product name → ${TEST_PRODUCTNAME}
# {{4}} next step → ${TEST_NEXTSTEP}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_CUSTOMERNAME}" },
        { "type": "text", "text": "${TEST_TICKETNUMBER}" },
        { "type": "text", "text": "${TEST_PRODUCTNAME}" },
        { "type": "text", "text": "${TEST_NEXTSTEP}" }
      ]
    }

  ]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
    *'"sent":true'*) ok=1 ;;
    *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
    echo "Message sent to client."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    echo "$BODY" >&2
    exit 1
fi

Response and delivery status

HTTP 2xx and JSON "sent": true mean 1MSG accepted the message for sending — not that it already reached the customer's phone. Save the id field (looks like wamid.…) to correlate delivery callbacks.

200 OKResponse
{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}
  • sent

    Accepted for sending — not yet on the customer's phone

  • id

    Store it; delivery callbacks and hookInfo are keyed on this

Delivery statuses and webhooks →

Common errors

StatusAPI responseCauseFix
200Message was not sent: template is not definednamespace, template or language is missing from the request body.Send all three. Take namespace and the exact template name from GET /templates; language is an object: {"policy": "deterministic", "code": "en"}.
200template name (…) does not exist in <language>The template is approved in a different language than the one requested.Use the exact language code the template was approved in (for example es_MX is not the same as es). Check it in GET /templates.
200Message was not sent: provide chatId, phone, bsuid, or usernameNo recipient the channel could resolve.Pass exactly one recipient: phone (country code plus number, digits only), chatId (for example [email protected]) or bsuid.

All error codes →

Common questions

Связанные

Заказы и доставка
WhatsApp Business API для уведомления о неполучении ответа на заказ
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, если он не ответил на предыдущее сообщение по заказу в ожидаемое время.
Заказы и доставка
WhatsApp Business API для уведомления о передаче заказа в доставку
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда его заказ передаётся партнёру по доставке для выполнения последнего этапа.
Заказы и доставка
WhatsApp Business API для подтверждения доставки заказа
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда его заказ отмечен как доставленный.
Заказы и доставка
WhatsApp Business API для уведомления об отмене заказа
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда заказ отменён.
Заказы и доставка
WhatsApp Business API для уведомлений о новом маршруте или поездке
Сценарий отправляет менеджеру или диспетчеру персонализированный шаблон WhatsApp, когда создаётся новый маршрут доставки или рейс.
Заказы и доставка
WhatsApp Business API для подтверждения нового заказа
Сценарий отправляет клиенту персонализированный шаблон WhatsApp сразу после оформления нового заказа.
Заказы и доставка
WhatsApp Business API для уведомления о неудачной попытке доставки
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, если не удалось доставить.
Заказы и доставка
WhatsApp Business API для обновления — указать место получения
Этот сценарий отправляет местоположение с помощью sendLocation в течение 24-часового окна обслуживания клиентов.

Интегрируйте WhatsApp за часы
без проблем с инфраструктурой