How to send SMS messages with Modica

Configure Modica credentials, sender settings, and delivery status webhooks in Knock.

Knock integrates with Modica to send SMS notifications to your recipients.

Features

Delivery tracking
Bounce support
Knock link tracking
Per environment configuration
Sandbox mode

Getting started

You can create a new Modica channel in the dashboard under the Channels and sources page in your account settings. From there, you'll need to configure the channel for each environment you have.

Knock sends messages through Modica's REST API v2, which authenticates each request with your gateway application name and password. You can find both on the REST API v2 configuration page in Modica.

Channel configuration

Configure the following settings per environment. Navigate to Channels and sources in your dashboard account settings and select your Modica channel. Under Environment configurations, click the environment you'd like to configure to expand its settings, then click "Save changes" when you're done. Expand Advanced for additional options, including overrides and conditions.

Fields marked with an * are required.

Application namestring*

The gateway application name from Modica. Knock sends this as the HTTP Basic username.

Passwordstring*

The application password from Modica.

Sourcestring

The short code or virtual number messages originate from. Leave this blank to use the source provisioned on the gateway application.

Maskstring

An alphanumeric source mask. It can be sent with a source. Modica ignores a mask that is not configured on the account.

Classstring

The application class used for routing and billing. Modica defaults this to mt_message. It must be 30 characters or fewer.

Incoming webhookboolean

Whether to receive message delivery status updates from Modica via webhook.

Sandbox modeboolean

Whether to enable sandbox mode for your Modica channel.

Link trackingboolean

Whether to enable Knock link-click tracking.

When configured, the optional payload overrides set here will apply to all SMS notifications sent from this channel in the configured environment. Learn more about SMS channel overrides here.

Payload overridesJSON (string) | liquid

Provide a JSON object to merge into the API payload that is sent to the downstream provider.

Set optional per-environment conditions for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.

Recipient data requirements

In order to send an SMS notification you'll need a valid phone_number property set on your recipient. Modica expects the number in international format, for example +64211234567.

Delivery status webhooks

When enabled, Modica sends delivery receipts directly to Knock, so message statuses update as soon as the carrier reports them. Without a webhook, Knock polls Modica for delivery status, and a receipt that arrives after polling ends won't update the message.

Modica only sends delivery receipts to a callback URL you've configured, so you'll need to set this up in both Knock and Modica.

Enable delivery status webhooks in Knock

Navigate to Channels and sources in your Knock dashboard
Select your Modica channel
Under Environment configurations, click the environment you want to configure to expand its settings
Turn on Incoming webhook
Copy the Webhook URL - you'll need this in the next step
Click "Save changes"

Add the DLR callback URL in Modica

Open the REST API v2 configuration page in Modica
Set the DLR callback URL to the webhook URL from Knock
Save your changes

Each environment has its own webhook URL, so repeat these steps for each environment you want to track, using the Modica application that environment sends from.

Supported delivery statuses

When delivery status webhooks are enabled for Modica, Knock updates message statuses based on these delivery receipts:

Modica status	Knock status	Description
received	`delivered`	The recipient received the message
rejected	`bounced`	The carrier rejected the message
expired	`bounced`	The carrier couldn't deliver the message in time, such as when a phone is off
failed	`bounced`	Delivery failed due to a carrier connectivity issue
dead	`bounced`	A Modica administrator stopped the message

Other Modica statuses, such as sent, don't change the message status in Knock. Learn more about the bounced status in the message statuses docs.

Troubleshooting

If delivery status updates aren't appearing in Knock:

Check the DLR callback URL. Verify that the URL on the REST API v2 configuration page in Modica matches the webhook URL for the environment you're sending from.
Verify the phone number format. Ensure recipients have phone numbers in international format, such as +64211234567.
Check your gateway's API version. A Cannot_Route error usually means your Modica gateway isn't set up for REST API v2. Modica's support team can confirm which version your gateway uses.