​

Phonovation Developer Portal instructions

​

About this project

• This repository contains the public Phonovation Developer Portal, built with Mintlify.
• Write for developers integrating SMS messaging into their applications, with particular attention to customers sending messages to Irish recipients.
• Pages are MDX files with YAML frontmatter. Site configuration and navigation live in docs.json.
• API definitions live in openapi/. Endpoint pages use an openapi frontmatter reference to render the matching operation.
• The site uses the mint theme, Font Awesome icons, and the Outfit font. Put shared visual overrides in style.css only when docs.json cannot express them.
• Use docs.json, never the deprecated mint.json.

​

Information architecture

• InteractSMS 1.5 is the current and default version. It contains the existing Guides, API Reference, and Legacy APIs tabs.
• Guides explains integration workflows: authentication, sending SMS, Sender IDs, notifyId, webhooks, delivery receipts, inbound messages, security, compliance, and tools.
• API Reference documents the current OAuth-based Phonovation SMS API v2 and its webhook payloads.
• Legacy APIs documents the supported v1 JSON and URL-encoded APIs. Treat these APIs as long-term support only and direct new integrations to v2.
• Phonovation 1.0 is the next-generation version and is marked Coming soon. Until substantive documentation is approved, keep its preview page concise, unindexed, and free of release dates or unverified feature claims.
• Keep the Phonovation 1.0 changelog limited to approved public milestones. Do not present a documentation preview as a platform release.

1. Read docs.json and search for an existing page that covers the subject.
2. Update an existing page instead of duplicating information when possible.
3. Read at least two nearby pages to match their scope, terminology, and component usage.
4. Add every new public page to the appropriate group in docs.json. A page omitted from navigation is intentionally hidden.

​

Product terminology

• Use Phonovation for the company and platform.
• Use Phonovation Developer Portal for this documentation site. The homepage may use Phonovation Developer Hub as its page title.
• Phonovation was previously called InteractSMS. Use InteractSMS 1.5 for the current version label and when explaining the former platform name, but continue to call the platform Phonovation or Phonovation SMS in general content.
• Use Phonovation SMS API v2 or SMS API v2 for the current technical API. Its interactsms.com service hostnames and login URL remain from the former platform name.
• Use Phonovation 1.0 for the next-generation platform. Its APIs will use Phonovation domains, but do not invent or publish specific hostnames until they are approved.
• Use Auth API for https://auth.interactsms.com and SMS API for https://api.interactsms.com when distinguishing the two services.
• Use legacy API, JSON API (v1), or URL-Encoded API (v1) for v1 integrations. Do not recommend v1 for new integrations.
• Use campaign for a v2 send request and message for an SMS sent to one recipient.
• Use recipient for the person or number receiving a message. Use customer for a Phonovation customer or account holder.
• Write Sender ID with this capitalization. A Sender ID must be approved on the customer’s account. Alphanumeric Sender IDs used for Irish recipients must be registered with ComReg.
• Introduce delivery receipt (DLR) on first use, then use DLR.
• Use webhook for the v2 SMS processing callback, delivery receipt for the later handset delivery result, and inbound relay for an incoming SMS forwarded to a customer endpoint. Do not conflate these events.
• Write the request field as notifyId, the webhook field as NotifyId, and relay or DLR fields as SMS-NotifyId.
• Use dedicated longcode and shortcode as single words, matching the existing guides.
• Use OAuth 2.0, JWT access token, bearer token, ComReg, GDPR, and ePrivacy Regulations with this capitalization.
• Use cURL, JavaScript, Python, C#, Java, and PHP for language names and code-tab titles.

​

Writing style

• Use active voice and address the reader as you.
• Keep sentences concise and focused on one idea.
• Use sentence case for headings. Preserve exact product terms such as Sender ID, API Reference, and MCP Server where applicable.
• Lead with what the reader can accomplish, then explain prerequisites and steps.
• Use numbered headings only for genuine sequential workflows, as in the quickstart.
• Use contractions naturally. Avoid formal filler, marketing claims, and unnecessary repetition.
• Bold UI labels and important outcomes. Use inline code for fields, values, URLs, commands, file names, and paths.
• Use root-relative links without .mdx extensions for internal pages, for example /guides/authentication.
• Use descriptive link text. Do not use “click here.”
• Use em dashes sparingly and match the surrounding page’s punctuation.
• Every handwritten guide or overview page must have a title, description, and appropriate Font Awesome icon in frontmatter. Endpoint pages may inherit their descriptions from the referenced OpenAPI operation.

​

Page patterns and Mintlify components

• Use <Steps> for sequential procedures and <CodeGroup> when showing the same operation in multiple languages.
• Use <CardGroup> and <Card> for short navigation choices or next steps, not as a substitute for substantive content.
• Use <Info> for prerequisites or useful context, <Warning> for security, billing, delivery, or compliance risks, and <Note> for details readers can safely skip.
• Use Mermaid only when a flow or sequence is materially clearer than prose. Give every diagram a concise title and label nodes in plain language.
• Use tables for exact mappings, limits, field comparisons, status values, and version differences.
• Put exact repeated examples in snippets/ and import them into each page. Keep snippets narrowly scoped because Mintlify’s web editor does not support editing imported snippet content.
• End task-oriented overview pages with relevant next steps when useful.
• Do not import a custom component when a built-in Mintlify component is sufficient.

​

Code examples

• Prefer examples in the languages configured in docs.json: cURL, Python, C#, Java, PHP, and JavaScript.
• For multi-language API workflows, keep request values, behavior, and highlighted lines equivalent across tabs.
• Use realistic but synthetic Irish and international phone-number shapes, such as 353861234567. Never use real customer data.
• Use placeholders such as YOUR_USERNAME, YOUR_PASSWORD, YOUR_ACCESS_TOKEN, and YOUR_CLIENT_SECRET. Never commit credentials, tokens, personal data, or production secrets.
• Use environment variables or a secrets manager when an example demonstrates credential handling.
• Include language identifiers and concise titles on fenced code blocks. Use Mintlify line highlighting only when it directs attention to the relevant lines.
• Keep examples runnable where practical. Include required imports and content types.
• Show dates and scheduled timestamps in ISO 8601 UTC format. Relay and DLR timestamps may use the documented gateway format yyyy-MM-dd HH:mm:ss.
• Do not invent endpoint behavior, limits, status codes, schemas, SDK support, or error messages. Verify technical details against the relevant OpenAPI file and existing guide.

​

API documentation standards

• Treat files in openapi/ as the source of truth for endpoint methods, paths, parameters, request bodies, response schemas, servers, and example payloads.
• Keep an endpoint page’s openapi frontmatter reference synchronized with the exact file, HTTP method, and path in the specification.
• When behavior is explained in both a guide and an OpenAPI description, update both locations so they do not drift.
• Keep v2, legacy v1, webhook, DLR, and inbound relay examples in their respective sections and specifications.
• Explain authentication requirements before the first authenticated request.
• State consequential behavior near the example it affects, including partial delivery, credit usage, Sender ID restrictions, token expiry, callback verification, and retry handling.
• Distinguish API acceptance from handset delivery: the v2 webhook reports processing, while a DLR reports the later network delivery result.
• Recommend notifyId for recipient-level correlation across sends, webhooks, DLRs, and linked inbound replies.

​

Safety, compliance, and factual boundaries

• The SMS API has no sandbox. State clearly that requests use the live production system and can consume message credits when test instructions could trigger a send.
• Recommend testing with a small number of the developer’s own numbers before a production rollout.
• Never suggest hardcoding credentials or putting credentials in URLs, source control, screenshots, or logs.
• Do not claim that a message was delivered when only the API or processing webhook accepted it. Use the DLR to describe handset delivery status.
• Preserve Irish compliance guidance: marketing recipients need an opt-out mechanism, opt-outs must be honoured, and applicable Sender IDs must be registered with ComReg.
• Present compliance content as integration guidance, not individualized legal advice. Do not invent regulatory requirements; verify uncertain or time-sensitive claims before changing them.
• Document only public integration behavior. Do not expose internal infrastructure, private endpoints, customer information, account-specific limits, credentials, or support procedures that are not already public.
• Do not promise uptime, throughput, delivery times, or account limits unless a verified source in the repository supports the claim.
• Direct account provisioning, Sender ID registration, credential access, webhook configuration, and account-specific questions to support@phonovation.com or the contact specified by the relevant existing page.

​

Privacy and analytics

• Keep the iubenda CMP and consent-managed integrations in privacy.js. Do not add the same provider through docs.json, because that can load it twice or before consent.
• Use iubenda purpose 4 for measurement and purpose 5 for marketing. Google Tag Manager currently requires both because its container can dispatch tags from both categories.
• Keep integrations.cookies synchronized with the phonovation-measurement-consent=granted local-storage signal written by privacy.js. This signal controls Mintlify telemetry and page feedback.
• Treat consent failure as denial. Do not load Clarity, ZoomInfo, HubSpot, GTM, or other non-essential scripts when the CMP cannot start.

​

Validation

1. Confirm frontmatter is valid and navigation paths match real files.
2. Validate changed OpenAPI documents and verify every referenced operation exists.
3. Check internal links are root-relative and omit file extensions.
4. Check examples across languages for equivalent behavior and safe placeholder data.
5. Run mint validate.
6. Run mint broken-links.
7. Preview significant layout or component changes with mint dev.
8. Report any validation command you could not run and why.