Send WhatsApp messages through Courier

Courier uses the Twilio API for WhatsApp as the delivery partner.

Prerequisites

A Twilio account with WhatsApp enabled
Your Twilio Account SID and Auth Token
A WhatsApp-enabled “From” number in Twilio

Setup

Get your Twilio credentials

In Twilio, open the console and copy your Account SID and Auth Token. Your WhatsApp sender is the “From” number.

Configure in Courier

Open the in Courier, enter your Twilio Account SID, Auth Token, and “From” number, then save.

Profile requirements

WhatsApp addresses the recipient by phone number, so the profile you send to needs a phone_number. Store it once with , which merges into the profile and creates it if it does not exist:

const profile = await client.profiles.create('user_123', {
  profile: {
    phone_number: '+15551234567',
  },
});

profile = client.profiles.create(
    user_id="user_123",
    profile={
        "phone_number": "+15551234567",
    },
)

curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "phone_number": "+15551234567"
    }
  }'

profile = courier.profiles.create(
  "user_123",
  profile: {
    phone_number: "+15551234567"
  }
)

profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"phone_number": "+15551234567",
		},
	},
)

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("phone_number", JsonValue.from("+15551234567"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);

$profile = $client->profiles->create('user_123', profile: [
  'phone_number' => '+15551234567',
]);

ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
    },
};
var profile = await client.Profiles.Create(parameters);

courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"phone_number":"+15551234567"}'

With Courier MCP, create a profile for user_123 with the phone number +15551234567.

Then send to user_id and Courier resolves the address. For a one-off with no stored profile, pass it inline instead: "to": { "phone_number": "+15551234567" }.

Send by user id

The call in every language, and the rest of the profile object.

Send to a recipient

Send to user id
Send to a phone number

Courier reads phone_number off the saved profile, so preferences apply and the value can change without touching this code.

const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, send my template to user_123 by email.

Pass it inline instead and nothing is stored. Swap this to object into the call on the other tab.

const { requestId } = await courier.send.message({
  message: {
    to: {
      phone_number: "+15551234567",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

response = client.send.message(
    message={
        "to": {
            "phone_number": "+15551234567",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "phone_number": "+15551234567"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      phone_number: "+15551234567"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15551234567"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15551234567").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'phone_number' => '+15551234567',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15551234567" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15551234567"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, send my template to +15551234567 by SMS.

Notification categories

WhatsApp allows these notification categories:

Marketing
Authentication
Utility

Other categories are likely to be rejected, including:

Account Update
Alert Update
Appointment Update
Auto-Reply
Issue Resolution
Payment Update
Personal Finance Update
Reservation Update
Shipping Update
Ticket Update
Transportation Update

WhatsApp template verification

WhatsApp reviews every template against its guidelines before you can send it.

Create the template

Structure: WhatsApp message templates are predefined messages with placeholders for dynamic content. A template can be text, media (images, documents), or interactive (buttons, list messages). Categories: Each template is categorized by use case, such as transactional updates, customer service, or alerts.

Submit the template for approval

Open the console: In the Twilio Console, go to the Messaging section. Create the template: In the WhatsApp Templates section, create a template. Provide the template name, category, language, and message content. Leave out promotional material, which WhatsApp disallows in templates. Submit for review: Submit the template for WhatsApp’s review.

WhatsApp approval process

WhatsApp checks the template against its policies. Review takes a few minutes to 24 hours. Two outcomes:

Approved: The template meets WhatsApp’s guidelines. You can now send it through the Twilio API.
Rejected: The template is rejected for promotional content, inappropriate language, or other policy violations. Fix the template and resubmit it.

Approved templates with Courier

Copy the approved template’s Twilio Content SID, which starts with HX. Paste it into the WhatsApp channel settings of your Courier template. Sends then reference that approved template through the .

A Courier template's WhatsApp channel settings with the Twilio Content SID pasted in — WhatsApp Template

On send, Courier calls Twilio with the template details. Twilio delivers the message over WhatsApp.

WhatsApp delivers your Twilio-approved template, not your Courier content.
Courier sends the Content SID and its variables, and Twilio renders the approved template. Your Courier template still drives routing, variables, and every other channel.

Key considerations

Content: Keep template content clear and non-promotional. Include every placeholder and give sample values so reviewers have context. Localization: Create and get approval for each language version of the template. Monitoring: Watch template performance. Frequent spam reports can cost you the ability to send. Update templates as WhatsApp guidelines change.

Overrides

covers the two levels and which one wins. A provider override changes the request body Courier sends to Twilio, or swaps the Twilio credentials and the From number.

Body overrides

A Content SID is required on every WhatsApp send. Set it on the template’s WhatsApp channel settings, or pass it per send as override.body.ContentSid. Without one the send fails with No Content SID specified. before reaching Twilio. Override body keys are capitalized before they are sent, so contentSid and ContentSid are equivalent. Use an override to select an approved template at send time:

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555",
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          body: {
            ContentSid: "HXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+15555555555",
        },
        "providers": {
            "twilio-whatsapp": {
                "override": {
                    "body": {
                        "ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+15555555555"
      },
      "providers": {
        "twilio-whatsapp": {
          "override": {
            "body": {
              "ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555"
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          body: {
            ContentSid: "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15555555555"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"twilio-whatsapp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX",
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15555555555").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("twilio-whatsapp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "ContentSid", "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+15555555555',
    ],
    'providers' => [
      'twilio-whatsapp' => [
        'override' => [
          'body' => [
            'ContentSid' => 'HXXXXXXXXXXXXXXXXXXXXXXXXXXX',
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15555555555" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "twilio-whatsapp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15555555555"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"twilio-whatsapp": {"override": {"body": {"ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"}}}}'

With Courier MCP, send my template to +15555555555 on WhatsApp with a Content SID override.

Config overrides

Swap Twilio credentials or the “From” number at send time:

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555",
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          config: {
            accountSid: "RUNTIME_ACCOUNT_SID",
            authToken: "RUNTIME_AUTH_TOKEN",
            from: "+14155551234",
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+15555555555",
        },
        "providers": {
            "twilio-whatsapp": {
                "override": {
                    "config": {
                        "accountSid": "RUNTIME_ACCOUNT_SID",
                        "authToken": "RUNTIME_AUTH_TOKEN",
                        "from": "+14155551234",
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+15555555555"
      },
      "providers": {
        "twilio-whatsapp": {
          "override": {
            "config": {
              "accountSid": "RUNTIME_ACCOUNT_SID",
              "authToken": "RUNTIME_AUTH_TOKEN",
              "from": "+14155551234"
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555"
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          config: {
            accountSid: "RUNTIME_ACCOUNT_SID",
            authToken: "RUNTIME_AUTH_TOKEN",
            from: "+14155551234"
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15555555555"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"twilio-whatsapp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"accountSid": "RUNTIME_ACCOUNT_SID",
						"authToken": "RUNTIME_AUTH_TOKEN",
						"from": "+14155551234",
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15555555555").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("twilio-whatsapp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "accountSid", "RUNTIME_ACCOUNT_SID",
                        "authToken", "RUNTIME_AUTH_TOKEN",
                        "from", "+14155551234"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+15555555555',
    ],
    'providers' => [
      'twilio-whatsapp' => [
        'override' => [
          'config' => [
            'accountSid' => 'RUNTIME_ACCOUNT_SID',
            'authToken' => 'RUNTIME_AUTH_TOKEN',
            'from' => '+14155551234',
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15555555555" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "twilio-whatsapp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "accountSid": "RUNTIME_ACCOUNT_SID",
                            "authToken": "RUNTIME_AUTH_TOKEN",
                            "from": "+14155551234"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15555555555"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"twilio-whatsapp": {"override": {"config": {"accountSid": "RUNTIME_ACCOUNT_SID", "authToken": "RUNTIME_AUTH_TOKEN", "from": "+14155551234"}}}}'

With Courier MCP, send my template to +15555555555 on WhatsApp with different Twilio credentials.

Provider details

twilio-whatsapp

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Send WhatsApp messages through Courier

Prerequisites

Setup

Profile requirements

Send by user id

Send to a recipient

Notification categories

WhatsApp template verification

Create the template

Submit the template for approval

WhatsApp approval process

Approved templates with Courier

Key considerations

Overrides

Body overrides

Config overrides

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Profile requirements

Send by user id

​Send to a recipient

​Notification categories

​WhatsApp template verification

​Create the template

​Submit the template for approval

​WhatsApp approval process

​Approved templates with Courier

​Key considerations

​Overrides

​Body overrides

​Config overrides

​Provider details

Send to a specific provider

Prerequisites

Setup

Profile requirements

Send to a recipient

Notification categories

WhatsApp template verification

Create the template

Submit the template for approval

WhatsApp approval process

Approved templates with Courier

Key considerations

Overrides

Body overrides

Config overrides

Provider details