Send a private document link with the IllyVoIP SMS API

Send a short SMS directing an authorized recipient to a document in your own authenticated application. IllyVoIP delivers the text message; your application hosts the document and controls access. An SMS link is not an attachment, and delivery does not establish who opened the document.

Use a backend with authorized account API access and keep X-Api-Key out of browser code. The API base is https://api.illyvoip.com. Check HTTP status and the JSON result. Examples below are request templates, not records of completed transactions.

SMS submissions can incur charges. Use the standard IllyVoIP sender or a custom sender approved and available for this account. Recipient eligibility, content review, encoding and current service limits still apply. Store an Idempotency-Key with the exact request before submission; preserve both after an uncertain response.

1. Keep the document behind its existing access checks

Start with a document the recipient is permitted to view. Use an HTTPS route in your application that checks the signed-in user’s access on every request. A document reference in the URL is a locator, not proof of authorization. Avoid publishing the file in an open object-storage location just to make the link easier to send.

1. Confirm the document belongs to the intended customer context.
2. Choose a stable, recognizable application domain.
3. Require authentication and document authorization after the link opens.
4. Decide how expiry, replacement and document withdrawal will appear.
5. Keep API credentials, passwords and sensitive document content out of the URL.

This workflow does not require a bearer-token link. If your product already uses a separately reviewed one-time access mechanism, preserve its recipient binding, expiry and revocation policy. Do not improvise a long-lived secret URL and assume possession proves identity.

2. Bind the notification to the correct recipient

Resolve the intended recipient through your verified customer data and save the document reference, account, recipient and document version in one notification intent. Recheck permission before submission. A number entered into an unauthenticated public form must not be enough to trigger a private-document message.

If the document changes before the message is sent, decide whether the saved intent is still valid. If access is removed, cancel unsent work. A message already accepted by the SMS service is not recalled by changing your local queue, so the destination page must enforce current access even after dispatch.

3. Prepare the exact message

POST this shape to /api/v1/sms/messages, using real authorized values only when an actual send is intended:

{
  "from": "IllyVoIP",
  "to": ["+12025550123"],
  "message": "Your document is ready. Sign in to view it: https://example.com/account/documents/doc-example-001"
}

The number, domain and reference are illustrative. The example URL should require login and a document-access check. IllyVoIP does not host this page, shorten this link or issue a document-access token for you.

Avoid document titles that reveal sensitive information on a phone’s lock screen. Include enough recognizable context for the customer to understand the notification without placing financial, identity or medical details in the SMS. Check the complete URL and message encoding; do not silently truncate a link to meet a length target.

4. Send once and follow delivery

1. Persist the exact sender, destination, message and SMS idempotency key.
2. Submit from your authenticated backend and inspect the immediate result.
3. Store each accepted queued_message_ids value with the document-notification intent.
4. Read delivery status or process verified webhooks.
5. Keep rejected, failed and uncertain submissions separate from delivered notifications.

If the response is lost, reconcile the original request rather than generating another key and sending again. If the URL was wrong, first fix the application route and assess whether an explicit replacement notice is necessary. Do not automatically send repeated links in response to every page error.

5. Handle expired and withdrawn documents clearly

An expired link should explain the next step without revealing the document to an unauthenticated visitor. A signed-in authorized customer can request a replacement through your normal application workflow. Rate-limit that request and create a new deliberately tracked notification only when needed.

Do not mark a document read merely because the SMS was delivered or a URL was fetched. Messaging clients and security scanners can prefetch links. Record meaningful document access inside the authenticated application, and do not make a GET request perform an irreversible approval or acceptance.

6. Test access as well as messaging

Test the link while signed out, as the intended user, as another customer, after access removal and after expiry. Confirm each outcome is appropriate before submitting a real SMS. Use local fixtures for duplicate notification requests and an uncertain submission. Finally, an authorized delivery check should cover a handset opening the link and the intended login flow; a successful API submission alone does not test the document experience.

Related guides

• Send an SMS with the IllyVoIP API and track delivery
• Send IllyVoIP SMS from an authenticated website form
• Send a customer-feedback survey link through IllyVoIP SMS

Reference

Current instructions and technical reference: IllyVoIP API documentation.

Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.