> ## Documentation Index > Fetch the complete documentation index at: https://developers.phonovation.com/llms.txt > Use this file to discover all available pages before exploring further. # AGENTS # 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 Preserve the versioned navigation unless a task explicitly requires a restructure: * **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. Before adding content: 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 `` for sequential procedures and `` when showing the same operation in multiple languages. * Use `` and `` for short navigation choices or next steps, not as a substitute for substantive content. * Use `` for prerequisites or useful context, `` for security, billing, delivery, or compliance risks, and `` 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 Before finishing a documentation change: 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.