Delivyr SMS

Delivyr is an SMS partner for messages to US and Canada numbers. It sends only templates that Delivyr has approved - there is no free-text SMS through Delivyr. Delivyr runs its service and keeps its message data in the United States.

Who it is for

Businesses that send SMS to recipients in the US or Canada and already have, or are opening, an account with Delivyr. Your Joryio workspace can be hosted in the EU or the US; what matters is that the recipients have US or Canada (+1) numbers.

Connecting your Delivyr account

You bring your own Delivyr account and connect it yourself, from the Delivyr card in Integrations. You need two things from your Delivyr portal, both under Settings > General:

• your Delivyr Account ID
• a Delivyr API key

1. Open Integrations and choose Delivyr (under Messaging).
2. Enter the Account ID and the API key. If Delivyr gave your account a sending number, you can enter it too. Delivyr chooses the number it sends from, so Joryio only shows it as the sender; without it, the sender shows as "Delivyr".
3. Click Test connection to check the details with Delivyr, then Connect Delivyr. Joryio checks them again, connects the account to this workspace and reads your templates for the first time.

Once connected, the card shows the Account ID, the sender, when the templates were last synced and how many there are, with Test connection, Refresh templates, Replace API key and Disconnect. The sender is what you pick in the SMS step of a campaign or journey.

• Who can connect. Only workspace admins - the Settings: Write permission - can connect, replace the key or disconnect. Other members see the card but cannot change it.
• The API key. It is stored encrypted and never shown again. To change it, use Replace API key; the new key is tested with Delivyr before it is saved.
• Several accounts per workspace, one workspace per account. A workspace can connect several Delivyr accounts - for example one per brand - and each is listed on the card with its own name. A Delivyr account can be connected to only one Joryio workspace: Delivyr keeps templates and the STOP list per account, so one account shared by two workspaces would share one STOP list.
• Demo workspaces. In a demo, connecting works only when Joryio has opened the demo to external connections.
• Billing. As with any SMS account you bring, you pay Delivyr for the messages under your own agreement with them, and Joryio adds its per-message platform fee.

If the connection test fails, the card says why - for example, that Delivyr did not accept the Account ID and API key, or did not answer. The connection is new, so if a check fails in a way that looks wrong, contact us and we will look at it with you. Contact us too if you do not have a Delivyr account yet.

Several Delivyr accounts

A workspace can send through more than one Delivyr account, for example one per brand. To add one, click Connect another Delivyr account under the connected accounts and enter its Account ID and API key as above. Give it a Name - the brand, for example - so you can tell the accounts apart: the name is shown on the card, in the SMS sender picker and on the SMS Templates page. Without a name, the first account is called "Delivyr" and the next ones "Delivyr" plus their Account ID. You can rename an account later with the pencil next to its name.

Each account is separate:

• Its own card. Each account has its own sender, templates, Test connection, Refresh templates, Replace API key and Disconnect. Disconnecting one account leaves the others connected.
• Its own templates. The SMS composer lists the templates of the account the chosen number belongs to, and names that account. A template belongs to one account and is sent only through it: if you switch the number to another account, pick one of that account's templates. The SMS Templates page shows which account each template belongs to, and asks which account a new template is for.
• Its own webhook URL and STOP list. Each account has its own delivery reports URL, and a STOP reported by one account unsubscribes the contact from that account's number only.

Disconnecting

Disconnect asks you to confirm first. It is refused while a campaign or journey that is live, scheduled, paused or waiting for approval still sends through Delivyr; the card lists them, so you can stop them or move them to another SMS number first. Drafts do not block it - launch review flags them once Delivyr is gone. Disconnecting removes the stored key, the Delivyr sender and the synced templates from this workspace. Nothing changes in your Delivyr account.

Templates

Every Delivyr message is a template. Your templates live on the SMS Templates page in Brand Studio, which appears once Delivyr is connected to your workspace.

• Made in the Delivyr portal. Templates you create and get approved in Delivyr's portal are synced into Joryio every 30 minutes, or straight away when you click Refresh from Delivyr.
• Made in Joryio. New template submits the template to Delivyr for review. It shows In review until Delivyr approves or rejects it.
• Delivyr system templates. Delivyr's own ready-made templates are listed too and can be sent without review.

Approved text cannot be edited. To change the wording, create a new template. Details, statuses and writing tips are on SMS Templates (Delivyr).

Sending in campaigns and journeys

When the number you send from belongs to a Delivyr account, the SMS composer shows a template picker instead of a message box - in campaigns and in the SMS step of a journey.

1. Pick an approved template. Templates still in review are not listed.
2. Fill each {{variable}} of the template. Type text or use Liquid personalization such as {{ user.first_name }}; each contact gets their own values when the message is sent.
3. Put the destination URL in {{link}}. Joryio sends it as its own tracked short link, so clicks are counted like any other SMS link.
4. Preview it and use Send test SMS to send the template to a test number.

Launch review flags an SMS on a Delivyr account that has no template, uses a template that is not approved, or leaves a variable empty. Whether those findings stop the launch depends on your workspace's launch review setting, but Delivyr itself never sends a message like that, so fix them before you launch. More on the composer: Delivyr accounts: approved templates.

Consent and opt-outs

• STOP is handled by Delivyr. When a recipient replies STOP, Delivyr stops sending to that number from your account. Joryio's own unsubscribes and consent rules still apply before anything is sent.
• Double opt-in. If double opt-in is turned on for your Delivyr account, Delivyr sends regular templates to a number only after the recipient confirms. Joryio has a matching contact status, Awaiting confirmation - see Subscription management.

Once delivery reports are set up, Delivyr's opt-outs are copied to the contact in Joryio: a STOP unsubscribes them from SMS, and a YES or UNSTOP reply re-subscribes them (and confirms a contact who is Awaiting confirmation). Without delivery reports, STOP replies and confirmations stay on Delivyr's side only. When Delivyr holds a contact's SMS opt-out, their contact page says so: you can still re-subscribe them in Joryio, but Delivyr keeps blocking SMS until they text START.

SMS double opt-in. Delivyr runs its own double opt-in, so when a workspace's SMS number is on a Delivyr account, Joryio's SMS double opt-in sends no second confirmation: new SMS opt-ins are recorded as usual and Delivyr holds texts to unconfirmed numbers ("Not confirmed yet") until the contact replies YES to Delivyr.

Delivery reports, opt-outs and replies

Delivyr sends delivery reports, opt-outs and replies only to a webhook you add in your Delivyr portal, and you write the content it sends for each event. Joryio gives you both: one webhook URL and a ready-made payload for each event. Until you add them, nothing comes back - Joryio knows a message was handed to Delivyr, but not whether it arrived, and STOP replies are not copied to the contact in Joryio.

Setting it up

1. Open Integrations > Delivyr and, under Delivery reports, click Set up delivery reports. Only workspace admins - Settings: Write - see the URL.
2. In your Delivyr portal, open Settings > Webhooks and create a webhook with the Webhook URL Joryio shows. The same URL is used for every event.
3. Subscribe the webhook to each event in the table below. For each event, paste Joryio's payload (JSONata) - the card has a Copy button for each one, and they are also listed below.
4. Save. The card shows when the last report arrived.

Delivyr event	What Joryio does with it
delivery_receipt	Marks the message Delivered, or Failed with the reason (undeliverable, expired, rejected by the carrier), in campaign and journey analytics.
rejected_message	Marks the message Failed with Delivyr's reason. Code 1 (opted out) also unsubscribes the contact from SMS.
opt_out	A STOP unsubscribes the contact from SMS for your Delivyr number. A YES or UNSTOP re-subscribes them - only when Joryio itself received that reply from the contact on your Delivyr number in the last 24 hours, and only for your Delivyr number: an SMS opt-out from your other numbers stays.
incoming_messages	Stores the reply on the contact; it can start or move a journey, and {{ reply.text }} reads it. A reply that is an opt-out word (STOP, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, OPT OUT and the rest of Joryio's opt-out list) also unsubscribes the contact from SMS - once, even when Delivyr's opt_out report for the same STOP arrives too. A START or YES reply does not re-subscribe them: only Delivyr's opt_out report does.
message_log	Confirms Delivyr accepted the message.
event_log	Counts clicks on links Delivyr tracks. Link previews by robots are skipped.

Each Delivyr account has its own webhook URL. With several Delivyr accounts, set up delivery reports on each account's card and paste that account's URL in that account's Delivyr portal. The payloads are the same for every account. A report that arrives on one account's URL is never matched to a message sent through another account.

The payloads

Paste each one, unchanged, as the payload of its event.

delivery_receipt

{ "version": 1, "type": "delivery_receipt", "id": id, "request_id": request_id, "message_log_id": message_log_id, "status": status, "status_mapped": status_mapped, "epoch": epoch }

rejected_message

{ "version": 1, "type": "rejected_message", "id": id, "request_id": request_id, "phone_number": phone_number, "rejection_code": rejection_code, "rejection_reason": rejection_reason }

opt_out

{ "version": 1, "type": "opt_out", "dml": dml, "phone_number": phone_number, "system_number": system_number, "incoming_log_id": incoming_log_id, "request_id": request_id }

incoming_messages

{ "version": 1, "type": "incoming_messages", "id": id, "from": from, "to": to, "body": body, "message_log_id": message_log_id, "request_id": request_id }

message_log

{ "version": 1, "type": "message_log", "id": id, "request_id": request_id, "sending_number": sending_number, "segments": segments, "testing": testing }

event_log

{ "delivyr_ignore": event != "click", "version": 1, "type": "event_log", "event": event, "message_log_id": message_log_id, "request_id": request_id }

• Version. Each payload carries "version": 1. If Joryio changes the payload, the card will say so; paste the new one then. A report whose payload Joryio does not recognize is refused and counted on the card.
• Keep the URL private. Anyone who has it can post reports and opt-outs for this workspace. If it leaks, click Create a new URL on the card: the old one stops working at once, and reports stop until you paste the new URL in Delivyr.
• Only your own messages count. Joryio matches every report to the message it sent from this workspace. A report it cannot match is counted on the card as not matched, and is never added to a contact or campaign.

Limits today

• No free-text SMS. Every message must be an approved template. A campaign created through the API with a free-text message on a Delivyr account is refused.
• US and Canada only. A send to a number outside +1 fails with "Delivyr sends to US and Canada (+1) numbers only" and is not retried.
• Delivery reports need the webhook. Delivered and failed messages, opt-outs and replies reach Joryio only after you add Joryio's webhook in your Delivyr portal - see Delivery reports, opt-outs and replies. Delivery reports are new: if the card shows reports that could not be matched to a message while Delivered stays at zero, contact us.

Public API

The same templates are available through the public REST API, for Delivyr workspaces only. See SMS templates in the Messaging API.