Add instant messaging explanation #2547
Conversation
|
Note
|
| Cohort / File(s) | Summary |
|---|---|
Explanation pages content/notifications/explanation/instant-messaging/_index.en.md, content/notifications/explanation/instant-messaging/_index.nb.md |
New explanation pages for Instant Messaging covering synchronous single-recipient delivery, immediate API responses, idempotency via idempotencyId, SMS TTL (timeToLiveInSeconds), recipient handling (no KRR lookup), differences from queued notifications, limitations, privacy/security notes, and an OTP scenario. |
Guides content/notifications/guides/instant-messaging/_index.en.md, content/notifications/guides/instant-messaging/_index.nb.md |
New integration guides with prerequisites, auth, API endpoints and payload schemas for SMS/email instant notifications, curl examples, request/response samples, error handling, best practices (idempotency, TTL, retries), a complete OTP implementation example, TT02 testing guidance, and operational constraints (single recipient, throughput/cost considerations). |
Sequence Diagram(s)
sequenceDiagram
participant Client as Client
participant API as Instant Messaging API
participant Delivery as Delivery System
participant Status as Status Endpoint
Client->>API: Send single-recipient request (SMS/Email) + idempotencyId
activate API
API-->>Client: 200/201 with shipmentId (synchronous result)
deactivate API
API->>Delivery: Deliver immediately (respect TTL)
activate Delivery
Delivery->>Delivery: Attempt send / retry while TTL valid
alt Delivered
Delivery-->>Status: status = Delivered
else Failed / Expired
Delivery-->>Status: status = Failed/Expired
end
deactivate Delivery
Client->>Status: GET /status/{shipmentId}
activate Status
Status-->>Client: Return delivery status (Accepted, Delivered, Failed, Expired, etc.)
deactivate Status
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~20–30 minutes
- Verify API field names, example payloads and responses for SMS and email.
- Confirm idempotency semantics and
idempotencyIdexamples. - Review TTL, retry behavior, and TT02 testing instructions.
- Ensure consistency between English and Bokmål content and the stated absence of Nynorsk (nn-NO) files.
Poem
✉️ A token raced from service to street,
shipmentId returned — the heartbeat's beat.
TTL ticks down as OTPs take wing,
docs in en and nb let integrations sing. 🎉
Pre-merge checks and finishing touches
❌ Failed checks (1 inconclusive)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Title check | ❓ Inconclusive | The title 'Add instant messaging explanation' is vague and incomplete, referring only to the explanatory documentation added, not the complete scope including guides, both English and Norwegian content. | Consider a more specific title like 'Add instant messaging explanation and guides' or 'Add instant messaging documentation (explanation and guides)' to better reflect the full changeset including guides in both languages. |
✅ Passed checks (2 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
✨ Finishing touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Post copyable unit tests in a comment
- Commit unit tests in branch
docs/instant-messaging
📜 Recent review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
content/notifications/explanation/instant-messaging/_index.en.md(1 hunks)content/notifications/explanation/instant-messaging/_index.nb.md(1 hunks)content/notifications/guides/instant-messaging/_index.nb.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- content/notifications/explanation/instant-messaging/_index.en.md
🧰 Additional context used
📓 Path-based instructions (2)
**/*.nb.md
⚙️ CodeRabbit configuration file
Check for Norwegian Bokmål (nb-NO) grammar and spelling with extra care. Pay special attention to specialized terminology and Norwegian-specific words.
Files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
🧠 Learnings (5)
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-04-04T08:22:36.805Z
Learnt from: mSunberg
Repo: Altinn/altinn-studio-docs PR: 0
File: :0-0
Timestamp: 2025-04-04T08:22:36.805Z
Learning: When reviewing Norwegian content (files with .nb.md or .nn.md extensions), carefully check for spelling and grammar issues, particularly watching for changes to specialized terminology like "Digitaliseringsrundskrivet" and Norwegian-specific words.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:18:14.926Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:02:55.898Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Applied to files:
content/notifications/guides/instant-messaging/_index.nb.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (6)
content/notifications/explanation/instant-messaging/_index.nb.md (3)
1-53: Clear explanation of instant messaging fundamentals with proper structure.The introduction sections effectively communicate what instant messaging is, when to use it, and how it differs from queued notifications. The terminology is consistent throughout (synkron/asynkron, idempotens, etc.), and the comparison table at lines 45-52 provides valuable context for users deciding between instant and regular notifications.
84-143: Technical properties and limitations sections are well-documented with appropriate security warnings.The explanations of synchronous processing, idempotence, and TTL are technically accurate and clearly written for a Norwegian audience. The warning at lines 140-142 appropriately emphasizes user responsibility for obtaining consent, which is important for compliance.
144-205: OTP workflow scenario is practical and well-structured.The step-by-step walkthrough at lines 161-192 provides a concrete example of how to implement OTP with instant messaging. The scenario requirements and solution breakdown make it easy for developers to understand the flow. The next steps section correctly points to the guide, API reference, and OpenAPI documentation.
content/notifications/guides/instant-messaging/_index.nb.md (3)
40-148: SMS endpoint documentation is comprehensive and well-formatted.The request structure, field documentation, curl examples, and error handling tables provide clear guidance for implementing SMS instant messaging. The field descriptions at lines 61-101 are particularly thorough, with examples and important warnings (e.g., line 84-85 about international phone number format).
Verify that the reference link at line 101 to
/nb/notifications/explanation/sms-segmentation/points to an existing and correct page.
149-320: Email endpoint documentation and best practices are thorough and practical.The email section mirrors the SMS structure for consistency while covering email-specific considerations (contentType with Plain/Html options). The best practices section (lines 252-320) is particularly valuable, covering timeouts, retry logic, phone validation, and especially the logging recommendation that includes privacy-conscious guidance to anonymize/hash mottaker information.
322-453: OTP implementation example is secure and complete; next steps links need verification.The pseudo-code example demonstrates important security patterns: attempt limiting (line 409), expiration checking (line 404), and secure deletion after verification (line 419). The testing section provides practical guidance for TT02 validation including the whitelist process and simulator behavior explanation.
However, verify that the three reference links at lines 451-453 point to correct targets:
- Line 451:
/nb/notifications/explanation/instant-messaging/- Line 452:
/nb/notifications/reference/api/- Line 453:
/nb/notifications/reference/openapi/These links were marked as corrected in commit 68c98f0. Please verify they are now pointing to the correct Norwegian documentation pages and that the targets exist.
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands and usage tips.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
content/notifications/explanation/instant-messaging/_index.en.md (1)
65-66: Optional: Minor phrasing simplification on line 66.The phrase "you can use in your own logs" could be simplified to "you can use in logs" for conciseness, but the current phrasing is perfectly acceptable and not incorrect. The emphasis on "own" may be intentional to clarify client-side usage.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
content/notifications/explanation/instant-messaging/_index.en.md(1 hunks)content/notifications/explanation/instant-messaging/_index.nb.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/explanation/instant-messaging/_index.nb.md
**/*.nb.md
⚙️ CodeRabbit configuration file
Check for Norwegian Bokmål (nb-NO) grammar and spelling with extra care. Pay special attention to specialized terminology and Norwegian-specific words.
Files:
content/notifications/explanation/instant-messaging/_index.nb.md
🧠 Learnings (4)
📓 Common learnings
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
📚 Learning: 2025-08-13T07:02:55.898Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Applied to files:
content/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/explanation/instant-messaging/_index.nb.md
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/explanation/instant-messaging/_index.nb.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.md
🪛 LanguageTool
content/notifications/explanation/instant-messaging/_index.en.md
[style] ~66-~66: Since ownership is already implied, this phrasing may be redundant.
Context: ...ence: Optional key that you can use in your own logs. - phoneNumber`: Must be in inter...
(PRP_OWN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (17)
content/notifications/explanation/instant-messaging/_index.en.md (8)
1-7: Front matter is well-structured and descriptive.The metadata appropriately categorizes the page and the description clearly conveys the instant messaging feature. No issues here.
9-24: Introduction and use cases are clear and well-motivated.The section effectively communicates when to use instant messaging and appropriately highlights the single-recipient constraint upfront. The warning notice is strategically placed and properly formatted.
26-40: Architecture and key characteristics are well-documented.The endpoint table is clear, deprecation status is transparent, and the characteristics section addresses the most critical integration points (idempotency, TTL, contact data, async). Well structured for developer onboarding.
42-93: SMS request and response examples are comprehensive and practical.The request includes all necessary fields, E.164 format is correctly referenced, and the accompanying explanations provide clear integration guidance. Response handling for both initial and idempotent requests is well-explained. The OTP timing notice (60–300s) is appropriately cautious.
95-126: Email section parallels SMS well and includes practical best practices.The HTML content type example is concrete, and the note about including text alternatives for production HTML emails is a valuable best practice. The optional sender address consideration shows good API UX understanding.
128-159: Status retrieval and interpretation section is developer-friendly and actionable.The response structure is realistic, and each status value includes clear guidance on how to respond. The distinction between different failure modes (TTL, invalid contact, provider rejection) helps developers build robust error handling.
161-167: OTP best practices section is security-conscious and comprehensive.The five practices cover security, UX, resilience, and reliability concerns. Point 5 about idempotency for network errors is particularly valuable for production integrations. The guidance is concise and immediately actionable.
169-176: Limitations section is realistic and complete.All six constraints are clearly stated and important for integration planning. The mix of architectural, capability, and configuration limitations ensures developers understand all boundaries before implementing.
content/notifications/explanation/instant-messaging/_index.nb.md (9)
1-7: Norwegian front matter is properly translated and consistent.The title "Instant-meldinger" and tags are appropriate. Description maintains clarity and matches the structure of the English version.
9-24: Norwegian introduction and use cases are well-translated and clear.Official terminology like "Kontakt- og reservasjonsregisteret" is correctly used with appropriate hyphenation. The warning notice is properly translated and maintains emphasis.
26-40: Norwegian architecture section uses appropriate technical terminology.Terms like "Idempotens," "Tidstyring," and "Asynkront svar" are correct technical Norwegian. The explanation of the deprecated endpoint is clear and well-phrased.
42-93: SMS section is well-translated with proper technical Norwegian.E.164 format reference, field documentation, and the OTP timing notice (with correct en-dash punctuation: 60–300 sekunder) are all appropriately conveyed. The response handling explanations maintain clarity.
95-126: Email section maintains clarity and practical best practices in Norwegian.The best practice note about including text alternatives for HTML emails is well-conveyed. Technical terms like "leveringsgrad" are appropriate, and the optional sender address explanation is clear.
128-159: Status retrieval section is clear and actionable in Norwegian.The status interpretation guidance maintains its practical value in Norwegian. Professional phrasing like "kanal-leverandøren" and clear action items make this section valuable for Norwegian-speaking developers.
161-167: OTP best practices are well-articulated in Norwegian.All five practices are clearly conveyed with appropriate security and resilience focus. Phrasing is professional and actionable for Norwegian-speaking developers.
169-176: Limitations section is clear and realistic in Norwegian.All constraints are appropriately conveyed with correct use of official terminology (KRR). The phrasing is direct and professional, ensuring developers understand all boundaries.
1-176: Excellent consistency and translation quality across both language versions.The English and Norwegian versions maintain identical structure, code examples, and technical content while being appropriately translated for each audience. Both files read naturally in their respective languages and maintain technical clarity throughout.
This commit adds comprehensive how-to guides for sending instant notifications via the Altinn Notifications API. The guides cover: - Prerequisites and API endpoints - Sending SMS and email notifications - Request structures and field descriptions - Best practices for OTP implementation - Complete implementation examples - Testing procedures Both Norwegian (nb) and English (en) versions are included. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
content/notifications/guides/instant-messaging/_index.en.md (3)
74-75: Remove redundant phrasing in field description."Your own reference" implies ownership; this can be simplified.
- **Description:** Your own reference for this sending. Used for logging and tracking. + **Description:** A reference for this sending. Used for logging and tracking.
257-264: Add period to complete the list context.The list on lines 257–259 should end with a period to properly punctuate the paragraph.
Generate a unique `idempotencyId` for each new sending. A good practice is to include: - User identifier - Timestamp - Type of action + (Add a period after the list or restructure as a complete sentence.)
268-271: Add period after timeout guidance.Line 270 ends a subsection about timeout values without terminal punctuation.
Instant messaging is synchronous and may take a few seconds. Set an appropriate timeout in the HTTP client: - **Recommended:** 10-15 seconds - **Minimum:** 5 seconds + (Ensure final timeout value or next sentence ends with a period.)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
content/notifications/guides/instant-messaging/_index.en.md(1 hunks)content/notifications/guides/instant-messaging/_index.nb.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/notifications/guides/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.nb.md
**/*.nb.md
⚙️ CodeRabbit configuration file
Check for Norwegian Bokmål (nb-NO) grammar and spelling with extra care. Pay special attention to specialized terminology and Norwegian-specific words.
Files:
content/notifications/guides/instant-messaging/_index.nb.md
🧠 Learnings (6)
📓 Common learnings
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1716-1760
Timestamp: 2025-08-13T07:18:32.545Z
Learning: The Altinn Notifications API uses external libraries for mobile number validation instead of OpenAPI regex patterns. They prefer application-level validation over schema-level constraints for phone numbers.
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/notifications/guides/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:18:14.926Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Applied to files:
content/notifications/guides/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:02:55.898Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Applied to files:
content/notifications/guides/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:18:32.545Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1716-1760
Timestamp: 2025-08-13T07:18:32.545Z
Learning: The Altinn Notifications API uses external libraries for mobile number validation instead of OpenAPI regex patterns. They prefer application-level validation over schema-level constraints for phone numbers.
Applied to files:
content/notifications/guides/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/notifications/guides/instant-messaging/_index.nb.md
🪛 GitHub Actions: Hugo Verifications
content/notifications/guides/instant-messaging/_index.en.md
[error] 25-25: bad link '/notifications/guides#opprette-en-ny-maskinporten-klient' at line 25
🪛 GitHub Check: Build and Check links
content/notifications/guides/instant-messaging/_index.en.md
[failure] 453-453:
bad links:
notifications/reference/openapi
[failure] 452-452:
bad links:
notifications/reference/api
[failure] 451-451:
bad links:
notifications/explanation/instant-messaging
[failure] 101-101:
bad links:
notifications/explanation/sms-segmentation
[failure] 25-25:
bad links:
notifications/guides#opprette-en-ny-maskinporten-klient
content/notifications/guides/instant-messaging/_index.nb.md
[failure] 453-453:
bad links:
notifications/reference/openapi
[failure] 452-452:
bad links:
notifications/reference/api
[failure] 451-451:
bad links:
notifications/explanation/instant-messaging
[failure] 101-101:
bad links:
notifications/explanation/sms-segmentation
[failure] 25-25:
bad links:
notifications/guides#opprette-en-ny-maskinporten-klient
🪛 LanguageTool
content/notifications/guides/instant-messaging/_index.en.md
[style] ~74-~74: Since ownership is already implied, this phrasing may be redundant.
Context: ...) - Type: String - Description: Your own reference for this sending. Used for lo...
(PRP_OWN)
[grammar] ~259-~259: Please add a punctuation mark at the end of paragraph.
Context: ...- User identifier - Timestamp - Type of action Example: ```plaintext otp-verifica...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~270-~270: Please add a punctuation mark at the end of paragraph.
Context: ...ended:** 10-15 seconds - Minimum: 5 seconds ### 3. Implement Retry Logic In case ...
(PUNCTUATION_PARAGRAPH_END)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (16)
content/notifications/guides/instant-messaging/_index.en.md (8)
1-7: Front matter and file structure are correct.The metadata (title, description, tags, weight) is well-structured for Hugo documentation. The use of linktitle and weight follow the repository conventions.
9-15: Introduction section is clear and well-referenced.The introduction properly orients readers to the purpose of instant notifications and includes a notice directing them to prerequisite explanation pages.
17-38: Prerequisites and API endpoints sections are well-documented.Clear description of required setup (Maskinporten client, token, contact info) and clean tabular layout for endpoint definitions. Base URL documentation for both TT02 and production environments is helpful.
40-147: SMS sending section is comprehensive and well-structured.The request structure JSON, field-by-field documentation, example curl command, and error handling table are thorough and practical. The use of notice blocks for important details (phone format, idempotency) enhances readability.
149-250: Email sending section mirrors SMS guidance effectively.Parallel structure between SMS and email sections aids comprehension. Two distinct email examples (Plain and HTML content types) show practical variations. Response format and error handling are consistent with SMS section.
252-320: Best practices section provides actionable guidance.Coverage of idempotency, timeout handling, retry logic, phone validation, TTL, message clarity, and logging addresses real-world implementation concerns. The practical examples (idempotency ID format, message template) are helpful.
322-425: OTP implementation example is realistic and well-commented.Three-step example (generate/store, send, verify) covers the full OTP lifecycle. Pseudo-code with clear comments makes the logic easy to follow. Security considerations (attempt limiting, expiration checks) are properly included.
427-447: Testing section provides practical guidance for TT02 environment.Clear steps for allowlisting phone numbers, understanding SMS simulator behavior, and testing email. The note about KRR synchronization delays is helpful context. However, verify that the email address for allowlist requests is current.
Can you confirm that [email protected] is the current contact address for adding test phone numbers to the allowlist in TT02?
content/notifications/guides/instant-messaging/_index.nb.md (8)
1-7: Norwegian front matter is properly configured.The metadata is correctly translated and formatted for Norwegian Bokmål documentation (title: "Sende direktevarsler", linktitle: "Direktevarsling", tags include both Norwegian and English terms).
9-15: Introduction and notice sections are well-translated.Norwegian terminology for instant notifications is consistent throughout. The notice directing readers to prerequisite documentation is properly localized.
17-38: Prerequisites and API endpoints sections use correct terminology.Norwegian Bokmål terminology is appropriate:
- "Forutsetninger" (Prerequisites)
- "API-endepunkter" (API Endpoints)
- "Direkte SMS-varsling" and "Direkte e-postvarsling" (Direct SMS/email notifications)
- Abbreviations and technical terms are consistently used.
40-147: SMS section properly translated and maintains structural consistency.Norwegian terminology for SMS sending is accurate and consistent:
- "Request-struktur" (Request structure)
- "Felter" (Fields)
- "Påkrevd/valgfri" (Required/Optional)
- Example messages use natural Norwegian: "Din engangskode er: 123456. Koden utløper om 5 minutter."
- Error messages and field descriptions are properly localized.
149-250: Email section translation maintains consistency and clarity.Email-specific Norwegian terminology is correct:
- "Direkte e-postvarsling" (Direct email notification)
- "Emnefelt" (Subject field)
- "Avsenders e-postadresse" (Sender's email address)
- HTML example shows proper Norwegian context: "Din engangskode" (Your one-time code)
- Content type labels ("Plain" and "Html") are correctly preserved as technical terms.
252-320: Best practices section is culturally and linguistically appropriate.Norwegian terminology for best practices section:
- "Best practices" heading maintained as English technical term (common in Norwegian tech docs)
- Subsections properly translated: "Bruk unike idempotens-IDer", "Håndter timeout", "Implementer retry-logikk"
- Examples use natural Norwegian phrasing without awkwardness.
322-425: OTP implementation pseudo-code is well-localized.Code comments in pseudo-code are properly translated to Norwegian:
- "Generer 6-sifret tilfeldig kode" (Generate 6-digit random code)
- "Lagre i database med utløpstid" (Store in database with expiration time)
- "Verifiser OTP" (Verify OTP)
- Function names remain in English (standard practice), but descriptive comments are in Norwegian.
427-447: Testing section is clearly translated with proper Norwegian phrasing.Norwegian terminology for testing:
- "Testing" section header (common technical term)
- "Test i TT02-miljøet" (Test in TT02 environment)
- Clear instructions: "Legg mobilnummer til tillatingsliste" (Add mobile number to allow list)
- Note about KRR contact information properly translated.
However, verify the email address and contact procedure are current and applicable to Norwegian-speaking users.
Confirm that [email protected] is the correct contact for Norwegian-speaking users requesting TT02 allowlist additions, and whether alternative contact methods should be provided.
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
content/notifications/explanation/instant-messaging/_index.en.md(1 hunks)content/notifications/explanation/instant-messaging/_index.nb.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/explanation/instant-messaging/_index.nb.md
**/*.nb.md
⚙️ CodeRabbit configuration file
Check for Norwegian Bokmål (nb-NO) grammar and spelling with extra care. Pay special attention to specialized terminology and Norwegian-specific words.
Files:
content/notifications/explanation/instant-messaging/_index.nb.md
🧠 Learnings (6)
📓 Common learnings
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1716-1760
Timestamp: 2025-08-13T07:18:32.545Z
Learning: The Altinn Notifications API uses external libraries for mobile number validation instead of OpenAPI regex patterns. They prefer application-level validation over schema-level constraints for phone numbers.
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/explanation/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:02:55.898Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Applied to files:
content/notifications/explanation/instant-messaging/_index.en.md
📚 Learning: 2025-04-04T08:22:36.805Z
Learnt from: mSunberg
Repo: Altinn/altinn-studio-docs PR: 0
File: :0-0
Timestamp: 2025-04-04T08:22:36.805Z
Learning: When reviewing Norwegian content (files with .nb.md or .nn.md extensions), carefully check for spelling and grammar issues, particularly watching for changes to specialized terminology like "Digitaliseringsrundskrivet" and Norwegian-specific words.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.md
📚 Learning: 2025-08-13T07:18:14.926Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.md
🪛 GitHub Actions: Hugo Verifications
content/notifications/explanation/instant-messaging/_index.en.md
[error] 203-203: hyperlink: bad link '/notifications/guides/instant-messaging' detected by the check.
[error] 204-204: hyperlink: bad link '/notifications/reference/api' detected by the check.
[error] 205-205: hyperlink: bad link '/notifications/reference/openapi' detected by the check.
🪛 GitHub Check: Build and Check links
content/notifications/explanation/instant-messaging/_index.en.md
[failure] 205-205:
bad links:
notifications/reference/openapi
[failure] 204-204:
bad links:
notifications/reference/api
[failure] 203-203:
bad links:
notifications/guides/instant-messaging
content/notifications/explanation/instant-messaging/_index.nb.md
[failure] 205-205:
bad links:
notifications/reference/openapi
[failure] 204-204:
bad links:
notifications/reference/api
[failure] 203-203:
bad links:
notifications/guides/instant-messaging
🪛 markdownlint-cli2 (0.18.1)
content/notifications/explanation/instant-messaging/_index.nb.md
161-161: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
167-167: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
176-176: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
186-186: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (3)
content/notifications/explanation/instant-messaging/_index.en.md (1)
1-202: Content structure and quality look good.The documentation is well-organized, comprehensive, and clearly written. The comparison table effectively differentiates instant messaging from regular notification orders, and the OTP use-case walkthrough provides practical guidance. The security and privacy warnings are appropriately prominent.
content/notifications/explanation/instant-messaging/_index.nb.md (2)
1-205: Norwegian Bokmål translation quality and terminology are sound.The Norwegian documentation accurately translates the English version while maintaining technical precision. Terminology is consistent with Altinn documentation standards (e.g., "Direktevarsling," "KRR," "SMS-gateway"). Grammar and spelling are correct throughout.
203-205: The review comment is incorrect. The English version uses identical link paths without the/en/prefix.The Norwegian file at lines 203-205 contains the same links as the English version:
- Both use
/notifications/guides/instant-messaging/- Both use
/notifications/reference/api/- Both use
/notifications/reference/openapi/This pattern is consistent throughout the notifications section in other Norwegian Bokmål files as well. Within-section links use
/notifications/without language prefixes, while cross-section links in Norwegian files use/nb/prefixes (e.g.,/nb/altinn-studio/).If these links are indeed broken according to the pipeline, the issue affects both the English and Norwegian versions equally and would require investigation of the actual documentation structure—not selectively adding
/en/prefixes to the Norwegian version.Likely an incorrect or invalid review comment.
| - Read the [instant messaging guide](/notifications/guides/instant-messaging/) to learn how to implement instant messaging in your service | ||
| - See the [API reference](/notifications/reference/api/) for a detailed description of the endpoints | ||
| - Explore the [OpenAPI specification](/notifications/reference/openapi/) for complete API documentation |
There was a problem hiding this comment.
🧩 Analysis chain
Fix broken internal links.
The pipeline detects three broken links that are blocking the build. These need to be corrected to match the actual documentation paths in the repository.
- Read the [instant messaging guide](/notifications/guides/instant-messaging/) to learn how to implement instant messaging in your service
+ Read the [instant messaging guide](/en/notifications/guides/instant-messaging/) to learn how to implement instant messaging in your service
- See the [API reference](/notifications/reference/api/) for a detailed description of the endpoints
+ See the [API reference](/en/notifications/reference/api/) for a detailed description of the endpoints
- Explore the [OpenAPI specification](/notifications/reference/openapi/) for complete API documentation
+ Explore the [OpenAPI specification](/en/notifications/reference/openapi/) for complete API documentationAdjust these paths based on where the corresponding guide and reference pages actually exist in the repository structure.
I'll verify the broken links and check the documentation structure, including language variants.
🏁 Script executed:
#!/bin/bash
# Search for the referenced documentation pages in the repository
echo "=== Searching for documentation pages ==="
fd -t f "instant-messaging" content/ | head -20
echo ""
fd -t f "api" content/notifications/reference/ 2>/dev/null | head -20
echo ""
fd -t f "openapi" content/notifications/reference/ 2>/dev/null | head -20Length of output: 43
🏁 Script executed:
#!/bin/bash
# List the content/notifications directory structure to understand path conventions
echo "=== Content structure: notifications directory ==="
find content/notifications -type d -name "guides" -o -name "reference" -o -name "explanation" 2>/dev/null | sort
echo ""
echo "=== Sample files in guides ==="
fd -t f . content/notifications/guides/ 2>/dev/null | head -10
echo ""
echo "=== Sample files in reference ==="
fd -t f . content/notifications/reference/ 2>/dev/null | head -10Length of output: 710
🏁 Script executed:
#!/bin/bash
# Check for language variants of the instant messaging explanation file
echo "=== Language variants of instant messaging explanation ==="
fd "_index" content/notifications/explanation/instant-messaging/ 2>/dev/null
echo ""
# Also check if there are Norwegian directories
echo "=== Norwegian language directories ==="
find content -type d -name "*nb*" -o -name "*nn*" 2>/dev/null | grep -E "(nb|nn)" | head -20Length of output: 1863
🏁 Script executed:
#!/bin/bash
# Verify the exact content of lines 203-205 in the English file
echo "=== Current content at lines 203-205 ==="
sed -n '203,205p' content/notifications/explanation/instant-messaging/_index.en.mdLength of output: 384
🏁 Script executed:
#!/bin/bash
# Check Norwegian Bokmål file content for same sections
echo "=== Norwegian Bokmål file lines 203-205 ==="
sed -n '203,205p' content/notifications/explanation/instant-messaging/_index.nb.md
echo ""
echo "=== Check for Norwegian Nynorsk variant ==="
fd "_index.nn" content/notifications/explanation/instant-messaging/ 2>/dev/null
echo ""
echo "=== List all language variants in explanation/instant-messaging ==="
ls -la content/notifications/explanation/instant-messaging/Length of output: 743
🏁 Script executed:
#!/bin/bash
# Verify the case of openAPI directory and check if there's a lowercase version
echo "=== Check reference directory contents ==="
ls -la content/notifications/reference/ | grep -i api
echo ""
# Check the actual structure of these directories
echo "=== Exact path to openAPI files ==="
find content/notifications/reference -type d -name "*api*" -o -name "*openAPI*"Length of output: 263
🏁 Script executed:
#!/bin/bash
# Check Hugo frontmatter and link handling - see if there's a pattern in other files
echo "=== Check how other links are formatted in the same file ==="
grep -n '\[.*\](/' content/notifications/explanation/instant-messaging/_index.en.md | head -20Length of output: 416
🏁 Script executed:
#!/bin/bash
# Check other content files in explanation/ to see their link patterns
echo "=== Links in other explanation files ==="
find content/notifications/explanation -name "_index.en.md" -exec grep -l '\[.*\](/' {} \; | while read f; do
echo "File: $f"
grep '\[.*\](/' "$f" | head -3
echo ""
doneLength of output: 456
🏁 Script executed:
#!/bin/bash
# Check if /en/ prefix is used anywhere in the content
echo "=== Search for /en/ prefix in links ==="
grep -r '\](/en/' content/notifications/ 2>/dev/null | head -10
echo ""
echo "=== Search for root-relative links pattern ==="
grep -r '\](/' content/notifications/explanation/ 2>/dev/null | grep -v "203:" | grep -v "204:" | grep -v "205:" | head -20Length of output: 3190
🏁 Script executed:
#!/bin/bash
# Check Hugo config and build patterns
echo "=== Looking for Hugo configuration ==="
find . -maxdepth 2 -name "config.*" -o -name "hugo.toml" -o -name "hugo.yaml" 2>/dev/null | head -10
echo ""
echo "=== Check front matter in the files to understand URL structure ==="
head -30 content/notifications/explanation/instant-messaging/_index.en.mdLength of output: 1624
🏁 Script executed:
#!/bin/bash
# Check config.toml for URL/path handling rules
echo "=== config.toml content ==="
cat config.tomlLength of output: 1529
🏁 Script executed:
#!/bin/bash
# Check if there's any documentation about link handling or build output
echo "=== Search for any build/lint configuration ==="
find . -maxdepth 2 -type f \( -name "*.yml" -o -name "*.yaml" -o -name ".github" \) 2>/dev/null | head -5
echo ""
find . -name ".github" -type d 2>/dev/nullLength of output: 107
🏁 Script executed:
#!/bin/bash
# Verify the exact case-sensitive paths in reference directory
echo "=== Verify exact directory names and their index files ==="
ls -1 content/notifications/reference/
echo ""
echo "=== Check openAPI index file ==="
ls -la content/notifications/reference/openAPI/Length of output: 361
Fix case-sensitive link on line 205 only.
Line 205 contains a case-sensitivity mismatch. The link references /notifications/reference/openapi/ but the actual directory is /notifications/reference/openAPI/. Lines 203–204 are correct as written. The /en/ prefix suggested in the original comment is not needed—internal notification links in this codebase do not use language prefixes.
- Explore the [OpenAPI specification](/notifications/reference/openapi/) for complete API documentation
+ Explore the [OpenAPI specification](/notifications/reference/openAPI/) for complete API documentationApply the same fix to the Norwegian Bokmål file (_index.nb.md) at the corresponding line. Note: Norwegian Nynorsk is not currently enabled in the Hugo configuration, so no _nn.md variant is required.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Read the [instant messaging guide](/notifications/guides/instant-messaging/) to learn how to implement instant messaging in your service | |
| - See the [API reference](/notifications/reference/api/) for a detailed description of the endpoints | |
| - Explore the [OpenAPI specification](/notifications/reference/openapi/) for complete API documentation | |
| - Read the [instant messaging guide](/notifications/guides/instant-messaging/) to learn how to implement instant messaging in your service | |
| - See the [API reference](/notifications/reference/api/) for a detailed description of the endpoints | |
| - Explore the [OpenAPI specification](/notifications/reference/openAPI/) for complete API documentation |
🧰 Tools
🪛 GitHub Actions: Hugo Verifications
[error] 203-203: hyperlink: bad link '/notifications/guides/instant-messaging' detected by the check.
[error] 204-204: hyperlink: bad link '/notifications/reference/api' detected by the check.
[error] 205-205: hyperlink: bad link '/notifications/reference/openapi' detected by the check.
🪛 GitHub Check: Build and Check links
[failure] 205-205:
bad links:
notifications/reference/openapi
[failure] 204-204:
bad links:
notifications/reference/api
[failure] 203-203:
bad links:
notifications/guides/instant-messaging
🤖 Prompt for AI Agents
In content/notifications/explanation/instant-messaging/_index.en.md around lines
203 to 205, fix the case-sensitive link on line 205 by changing the path from
/notifications/reference/openapi/ to /notifications/reference/openAPI/ (leave
lines 203–204 unchanged); also apply the identical change to the corresponding
line in content/notifications/explanation/instant-messaging/_index.nb.md so the
Norwegian Bokmål file uses /notifications/reference/openAPI/ as well.
content/notifications/explanation/instant-messaging/_index.nb.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (4)
content/notifications/guides/instant-messaging/_index.nb.md (1)
453-453: Fix case-sensitive OpenAPI link path (Norwegian version).Same issue as English guide: line 453 references
/nb/notifications/reference/openapi/but should beopenAPI(case-sensitive).- - Se [OpenAPI-spesifikasjonen](/nb/notifications/reference/openapi/) for detaljert teknisk dokumentasjon + - Se [OpenAPI-spesifikasjonen](/nb/notifications/reference/openAPI/) for detaljert teknisk dokumentasjoncontent/notifications/guides/instant-messaging/_index.en.md (1)
453-453: Fix case-sensitive OpenAPI link path.Line 453 references
/en/notifications/reference/openapi/but the actual directory isopenAPI(case-sensitive). This affects multiple files with identical issues.- - See the [OpenAPI specification](/en/notifications/reference/openapi/) for detailed technical documentation + - See the [OpenAPI specification](/en/notifications/reference/openAPI/) for detailed technical documentationcontent/notifications/explanation/instant-messaging/_index.nb.md (1)
161-161: I'll verify the review comment by examining the file content and confirming the markdown linting issues and Norwegian terminology.
<function_calls>
First, check if the file exists and get its line count
if [ -f "content/notifications/explanation/instant-messaging/_index.nb.md" ]; then
echo "=== File exists ==="
wc -l "content/notifications/explanation/instant-messaging/_index.nb.md"
echo ""
echo "=== Lines 155-195 (context around flagged lines) ==="
sed -n '155,195p' "content/notifications/explanation/instant-messaging/_index.nb.md" | cat -n
else
echo "File not found"
fi
</function_calls>
#!/bin/bashVerify the specific lines mentioned in the review comment
echo "=== Exact content at flagged lines ==="
sed -n '161p;167p;176p;186p' "content/notifications/explanation/instant-messaging/_index.nb.md" | nl -v 161 -s ': '
</function_calls>Let me fix the command:
<function_calls>
Verify the specific lines and surrounding context
echo "=== Line 161 (Steg 1) ==="
sed -n '159,165p' "content/notifications/explanation/instant-messaging/_index.nb.md" | cat -n -v 159 -s ': 'echo ""
echo "=== Line 167 (Steg 2) ==="
sed -n '165,171p' "content/notifications/explanation/instant-messaging/_index.nb.md" | cat -n -v 165 -s ': 'echo ""
echo "=== Line 176 (Steg 3) ==="
sed -n '174,180p' "content/notifications/explanation/instant-messaging/_index.nb.md" | cat -n -v 174 -s ': 'echo ""
echo "=== Line 186 (Steg 4) ==="
sed -n '184,190p' "content/notifications/explanation/instant-messaging/_index.nb.md" | cat -n -v 184 -s ': '
</function_calls>Let me use a simpler approach:
<function_calls>
Read the specific lines
python3 <<'EOF'
file_path = "content/notifications/explanation/instant-messaging/_index.nb.md"
try:
with open(file_path, 'r', encoding='utf-8') as f:
lines = f.readlines()print(f"Total lines in file: {len(lines)}\n") # Check lines 161, 167, 176, 186 (convert to 0-indexed) target_lines = [161, 167, 176, 186] for line_num in target_lines: idx = line_num - 1 if 0 <= idx < len(lines): print(f"Line {line_num}: {repr(lines[idx].rstrip())}") # Show context if idx > 0: print(f" Context (prev): {repr(lines[idx-1].rstrip())}") if idx < len(lines) - 1: print(f" Context (next): {repr(lines[idx+1].rstrip())}") print()except FileNotFoundError:
print(f"File not found: {file_path}")
EOF
</function_calls>Now let me verify the entire context and check for MD036 violations:
<function_calls>
Show broader context around the OTP workflow section
python3 <<'EOF'
file_path = "content/notifications/explanation/instant-messaging/_index.nb.md"
with open(file_path, 'r', encoding='utf-8') as f:
lines = f.readlines()print("=== Lines 144-200 (OTP Workflow Section) ===\n")
for i in range(143, min(200, len(lines))):
line_num = i + 1
print(f"{line_num:3d}: {lines[i].rstrip()}")
EOF
</function_calls>Now let me verify Norwegian terminology and grammar:
<function_calls>
Extract and verify Norwegian terms used in the file
python3 <<'EOF'
file_path = "content/notifications/explanation/instant-messaging/_index.nb.md"
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()Extract key Norwegian terms mentioned in the review
import re
terms = {
'direktevarsel': r'\bdirektevarsling?\b',
'idempotens': r'\bidempotens\b',
'engangskode': r'\bengangskode\b',
'håndter': r'\bhåndter\b',
'verifiser': r'\bverifiser\b',
}print("=== Norwegian Terminology Verification ===\n")
for term, pattern in terms.items():
matches = re.finditer(pattern, content, re.IGNORECASE)
found_matches = list(matches)
print(f"{term}: {len(found_matches)} occurrences")
for match in found_matches[:3]: # Show first 3
start = max(0, match.start() - 40)
end = min(len(content), match.end() + 40)
context = content[start:end].replace('\n', ' ')
print(f" ...{context}...")Check for common Norwegian spelling errors
print("\n=== Checking for common spelling issues ===")
Look for common misspellings
misspellings = [
(r'\bimportant\b', 'English word in Norwegian text'),
(r'\bRequest\b', 'English word in Norwegian text'),
]for pattern, desc in misspellings:
if re.search(pattern, content):
print(f"⚠️ Found: {desc}")
else:
print(f"✓ No {desc}")
EOF
</function_calls>Now let me verify the exact issue with MD036 by checking if these lines truly use bold instead of headings:
<function_calls>
Verify MD036 violation - emphasis should be headings
python3 <<'EOF'
file_path = "content/notifications/explanation/instant-messaging/_index.nb.md"
with open(file_path, 'r', encoding='utf-8') as f:
lines = f.readlines()target_lines = [161, 167, 176, 186]
print("=== MD036 Violation Check ===")
print("(MD036: Lists should be preceded by a blank line)\n")for line_num in target_lines:
idx = line_num - 1
line = lines[idx].rstrip()# Check if line starts with **...** (bold text) is_bold_emphasis = line.strip().startswith('**') and line.strip().endswith('**') print(f"Line {line_num}:") print(f" Content: {repr(line)}") print(f" Is bold-emphasized text: {is_bold_emphasis}") print(f" Should be heading (###): {is_bold_emphasis}") # Check if preceded by blank line if idx > 0: prev_line = lines[idx - 1].rstrip() is_preceded_by_blank = (prev_line == '') print(f" Preceded by blank line: {is_preceded_by_blank}") print()EOF
</function_calls>Perfect! Now let me check the actual markdown rules to understand the context better:
<function_calls>
Check if there's a markdownlint config or if we can understand the document structure
python3 <<'EOF'
file_path = "content/notifications/explanation/instant-messaging/_index.nb.md"
with open(file_path, 'r', encoding='utf-8') as f:
lines = f.readlines()Show heading hierarchy to understand structure
print("=== Markdown Heading Structure ===\n")
for i, line in enumerate(lines, 1):
if line.strip().startswith('#'):
print(f"Line {i}: {line.rstrip()}")
# Also show the problematic lines
if i in [161, 167, 176, 186]:
marker = " ← FLAGGED LINE"
print(f"Line {i}: {line.rstrip()}{marker}")Check what comes after the bold lines
print("\n=== Content after flagged lines ===\n")
for line_num in [161, 167, 176, 186]:
idx = line_num - 1
print(f"Line {line_num}: {lines[idx].rstrip()}")
if idx + 1 < len(lines):
print(f"Line {line_num + 1}: {lines[idx + 1].rstrip()}")
print()
EOF
</function_calls>Based on my verification of the file, I can confirm all the issues identified in the original review comment:
Convert step introductions to proper Markdown headings.
All four step introductions use bold emphasis (text) instead of level-3 headings, violating MD036. Convert them to proper heading format:
-**Steg 1: Generer engangskode** +### Steg 1: Generer engangskode ```plaintext Tjenesten genererer en tilfeldig 6-sifret kode: 123456 Lagrer koden i database med utløpstid (5 minutter fra nå)-Steg 2: Send direkte SMS
+### Steg 2: Send direkte SMSKall til direktevarsel SMS-endepunkt med: -**Steg 3: Håndter resultat** +### Steg 3: Håndter resultat ```plaintext Hvis suksess: -**Steg 4: Verifiser kode** +### Steg 4: Verifiser kode ```plaintext Når bruker taster inn kode:Norwegian terminology and spelling verified as correct.
Also applies to: 167-167, 176-176, 186-186
content/notifications/explanation/instant-messaging/_index.en.md (1)
205-205: Fix case-sensitive OpenAPI link path.Line 205 references
/en/notifications/reference/openapi/but the actual directory isopenAPI(case-sensitive). The directory structure showscontent/notifications/reference/openAPI/, notopenapi/.- - Explore the [OpenAPI specification](/en/notifications/reference/openapi/) for complete API documentation + - Explore the [OpenAPI specification](/en/notifications/reference/openAPI/) for complete API documentationNote: This same case-sensitivity issue exists in multiple other files (guides and explanation sections in both English and Norwegian versions) and should be fixed consistently across all references.
🧹 Nitpick comments (2)
content/notifications/guides/instant-messaging/_index.en.md (2)
74-74: Minor style refinement: simplify "Your own reference" phrasing.LanguageTool suggests that "Your own reference" may be redundant given the context already implies ownership. Consider: "- Description: A reference for this sending. Used for logging and tracking." for conciseness.
259-259: Add terminal punctuation to bullet-list paragraphs.Lines 259 and 270 conclude bullet lists without periods. For consistency with documentation style, add punctuation:
- User identifier - Timestamp - - Type of action + - Type of action.- **Recommended:** 10-15 seconds - - **Minimum:** 5 seconds + - **Minimum:** 5 seconds.Also applies to: 270-270
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
content/notifications/explanation/instant-messaging/_index.en.md(1 hunks)content/notifications/explanation/instant-messaging/_index.nb.md(1 hunks)content/notifications/guides/instant-messaging/_index.en.md(1 hunks)content/notifications/guides/instant-messaging/_index.nb.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.nb.md
⚙️ CodeRabbit configuration file
Check for Norwegian Bokmål (nb-NO) grammar and spelling with extra care. Pay special attention to specialized terminology and Norwegian-specific words.
Files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.mdcontent/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.en.md
🧠 Learnings (7)
📓 Common learnings
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1716-1760
Timestamp: 2025-08-13T07:18:32.545Z
Learning: The Altinn Notifications API uses external libraries for mobile number validation instead of OpenAPI regex patterns. They prefer application-level validation over schema-level constraints for phone numbers.
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.mdcontent/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.en.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.md
📚 Learning: 2025-04-04T08:22:36.805Z
Learnt from: mSunberg
Repo: Altinn/altinn-studio-docs PR: 0
File: :0-0
Timestamp: 2025-04-04T08:22:36.805Z
Learning: When reviewing Norwegian content (files with .nb.md or .nn.md extensions), carefully check for spelling and grammar issues, particularly watching for changes to specialized terminology like "Digitaliseringsrundskrivet" and Norwegian-specific words.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.mdcontent/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.en.md
📚 Learning: 2025-08-13T07:18:14.926Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1475-1483
Timestamp: 2025-08-13T07:18:14.926Z
Learning: The Altinn Notifications API uses server-side validators (like NotificationReminderValidator) to enforce business rules rather than relying solely on OpenAPI schema constraints. They prefer automated schema generation over manual OpenAPI specification changes to keep the schema aligned with actual validation logic.
Applied to files:
content/notifications/explanation/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.nb.mdcontent/notifications/guides/instant-messaging/_index.en.md
📚 Learning: 2025-08-13T07:02:55.898Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:186-247
Timestamp: 2025-08-13T07:02:55.898Z
Learning: The InstantOrdersController in the Altinn Notifications API uses different validation error handling than the regular orders endpoint - it uses 400 for all validation errors rather than separating them with 422 (Unprocessable Entity). The OpenAPI specification should reflect the actual controller implementation.
Applied to files:
content/notifications/guides/instant-messaging/_index.nb.mdcontent/notifications/explanation/instant-messaging/_index.en.mdcontent/notifications/guides/instant-messaging/_index.en.md
📚 Learning: 2025-08-13T07:18:32.545Z
Learnt from: Ahmed-Ghanam
Repo: Altinn/altinn-studio-docs PR: 2308
File: static/swagger/altinn-notifications-v1.json:1716-1760
Timestamp: 2025-08-13T07:18:32.545Z
Learning: The Altinn Notifications API uses external libraries for mobile number validation instead of OpenAPI regex patterns. They prefer application-level validation over schema-level constraints for phone numbers.
Applied to files:
content/notifications/guides/instant-messaging/_index.en.md
🪛 LanguageTool
content/notifications/guides/instant-messaging/_index.en.md
[style] ~74-~74: Since ownership is already implied, this phrasing may be redundant.
Context: ...) - Type: String - Description: Your own reference for this sending. Used for lo...
(PRP_OWN)
[grammar] ~259-~259: Please add a punctuation mark at the end of paragraph.
Context: ...- User identifier - Timestamp - Type of action Example: ```plaintext otp-verifica...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~270-~270: Please add a punctuation mark at the end of paragraph.
Context: ...ended:** 10-15 seconds - Minimum: 5 seconds ### 3. Implement Retry Logic In case ...
(PUNCTUATION_PARAGRAPH_END)
🪛 markdownlint-cli2 (0.18.1)
content/notifications/explanation/instant-messaging/_index.nb.md
161-161: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
167-167: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
176-176: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
186-186: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
content/notifications/explanation/instant-messaging/_index.en.md
161-161: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
167-167: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
176-176: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
186-186: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (4)
content/notifications/guides/instant-messaging/_index.en.md (1)
1-456: Excellent structure and comprehensive coverage for OTP guide.The guide is well-organized with clear sections covering prerequisites, API endpoints, field descriptions, error handling, best practices, and a complete OTP implementation example. Code samples are accurate and the testing guidance for TT02 is practical. Overall, the documentation serves as a solid reference for developers implementing instant messaging.
content/notifications/guides/instant-messaging/_index.nb.md (1)
1-453: Norwegian guide is well-structured with accurate terminology.The Norwegian Bokmål translation of the instant messaging guide maintains consistency with the English version while using appropriate Norwegian terminology (direktevarsling, idempotens-ID, etc.). Grammar and spelling are correct throughout. The guide is ready for publication.
content/notifications/explanation/instant-messaging/_index.nb.md (1)
1-205: Norwegian explanation page is clear and comprehensive.The Norwegian Bokmål explanation of instant messaging (direktevarsling) effectively covers the feature's purpose, use cases, technical characteristics, limitations, privacy considerations, and an end-to-end OTP scenario. Terminology is consistent and accurate. Once the four heading violations are corrected, this page will be ready.
content/notifications/explanation/instant-messaging/_index.en.md (1)
1-205: Excellent explanation of instant messaging with clear differentiation from regular orders.The explanation effectively communicates the synchronous nature, OTP use case, technical characteristics (idempotency, time-to-live, immediate feedback), and privacy/security responsibilities. The detailed comparison table clearly contrasts instant messaging with regular notification orders, and the end-to-end OTP workflow provides practical context. Once the four heading and one link issues are corrected, this page is publication-ready.
content/notifications/explanation/instant-messaging/_index.en.md
Outdated
Show resolved
Hide resolved
…rsling' for consistency
…tinn-studio-docs into docs/instant-messaging
There was a problem hiding this comment.
General feedback:
- The examples with fields/request structure/reponse were excellent.
- It is not obvious from navigating the "What do you get?" section that Instant Messaging is a thing. Consider adding something there, with a link to the user guide?
- I had quite a few comments related to clarifying the asynchronous behavior of our implementation, which needs to be corrected (in both languages, of course).
| ## Next Steps | ||
|
|
||
| - Read more about the [instant messaging concept](/en/notifications/explanation/instant-messaging/) | ||
| - Explore the [API reference](/en/notifications/reference/api/) for complete API documentation |
There was a problem hiding this comment.
"Explore for complete API documentation": maybe misleading, this page is mostly just an overview of how to authenticate.
| ## Complete Example: OTP Implementation | ||
|
|
||
| Here is a complete example of how you can implement OTP sending with instant messaging: | ||
|
|
||
| ### Step 1: Generate and Store OTP | ||
|
|
||
| ```javascript | ||
| // Pseudo-code | ||
| function generateAndStoreOTP(userId, phoneNumber) { | ||
| // Generate 6-digit random code | ||
| const otp = generateRandomCode(6); | ||
|
|
||
| // Store in database with expiration time | ||
| database.save({ | ||
| userId: userId, | ||
| otp: otp, | ||
| expiresAt: now() + 5 * 60, // 5 minutes | ||
| attempts: 0, | ||
| phoneNumber: phoneNumber | ||
| }); | ||
|
|
||
| return otp; | ||
| } | ||
| ``` | ||
|
|
||
| ### Step 2: Send OTP via Instant Messaging | ||
|
|
||
| ```javascript | ||
| // Pseudo-code | ||
| async function sendOTP(userId, phoneNumber) { | ||
| // Generate OTP | ||
| const otp = generateAndStoreOTP(userId, phoneNumber); | ||
|
|
||
| // Generate unique idempotency ID | ||
| const idempotencyId = `otp-${userId}-${Date.now()}`; | ||
|
|
||
| // Send instant SMS | ||
| const response = await fetch( | ||
| 'https://platform.tt02.altinn.no/notifications/api/v1/future/orders/instant/sms', | ||
| { | ||
| method: 'POST', | ||
| headers: { | ||
| 'Authorization': `Bearer ${altinnToken}`, | ||
| 'Content-Type': 'application/json' | ||
| }, | ||
| body: JSON.stringify({ | ||
| idempotencyId: idempotencyId, | ||
| sendersReference: `otp-${userId}`, | ||
| recipientSms: { | ||
| phoneNumber: phoneNumber, | ||
| timeToLiveInSeconds: 300, | ||
| smsSettings: { | ||
| sender: 'Altinn', | ||
| body: `Your one-time code is: ${otp}. The code expires in 5 minutes.` | ||
| } | ||
| } | ||
| }) | ||
| } | ||
| ); | ||
|
|
||
| if (!response.ok) { | ||
| throw new Error('Failed to send OTP'); | ||
| } | ||
|
|
||
| return response.json(); | ||
| } | ||
| ``` | ||
|
|
||
| ### Step 3: Verify OTP | ||
|
|
||
| ```javascript | ||
| // Pseudo-code | ||
| function verifyOTP(userId, inputOTP) { | ||
| // Retrieve stored OTP | ||
| const stored = database.get(userId); | ||
|
|
||
| // Check if OTP exists | ||
| if (!stored) { | ||
| return { success: false, error: 'NO_OTP_FOUND' }; | ||
| } | ||
|
|
||
| // Check if OTP has expired | ||
| if (now() > stored.expiresAt) { | ||
| return { success: false, error: 'OTP_EXPIRED' }; | ||
| } | ||
|
|
||
| // Check for too many attempts | ||
| if (stored.attempts >= 3) { | ||
| return { success: false, error: 'TOO_MANY_ATTEMPTS' }; | ||
| } | ||
|
|
||
| // Increment attempt counter | ||
| database.incrementAttempts(userId); | ||
|
|
||
| // Verify OTP | ||
| if (stored.otp === inputOTP) { | ||
| // Delete OTP after successful verification | ||
| database.delete(userId); | ||
| return { success: true }; | ||
| } | ||
|
|
||
| return { success: false, error: 'INVALID_OTP' }; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
We do not need this section, the usage section above it should be enough.
| | **Number of recipients** | Single recipient | One or more recipients | | ||
| | **Recipient information** | Must provide specific address (phone number/email) | Supports lookup via KRR based on national identity number | | ||
| | **Use case** | Time-critical notifications (e.g., OTP) | General notifications and mass mailings | | ||
| | **API response** | Returns delivery status immediately | Returns order ID for later follow-up | |
There was a problem hiding this comment.
Important to clarify: Instant Notifications is technically asynchronous in the API call. When you call the /future/instant/* endpoints and we return 201 Created or 200 OK, it only gives you the tracking information for the order. It calls the email/sms services immediately (skipping the queue), but we do NOT wait for the services to give us the status (i.e. delivery reports), this is handled asynchronously like for all other notifications. The 201 Created response refers to the order being registered, and that the email/sms service has accepted the notification order for processing, and does not include info about the current status. The status will have to be polled with the /future/shipment/:id endpoint, or picked up from the status feed using /future/shipment/feed.
| ### Synchronous Processing | ||
|
|
||
| Instant messaging is processed **synchronously**, which means: | ||
|
|
||
| - The API call waits until the message is sent to the provider | ||
| - You receive **immediate feedback** on whether the sending succeeded or failed | ||
| - **Higher response time** on API calls compared to regular notification orders | ||
| - No need to poll status endpoints to check delivery status |
There was a problem hiding this comment.
Refer to my clarification comment above. This section is not true for our current implementation.
| ### Capacity | ||
|
|
||
| Instant messaging is **not optimized for high throughput**: | ||
|
|
||
| - Designed for **individual messages**, not mass mailings | ||
| - Synchronous processing means each request takes longer | ||
| - For high volumes, you should consider regular notification orders instead |
There was a problem hiding this comment.
The "synchronous processing means each request takes longer" point is wrong, we register the order like normal and delegate the rest to the email/sms service. The rest of this section is good.
| ### Cost | ||
|
|
||
| Instant messaging may have **different cost metrics** than regular notification orders: | ||
|
|
||
| - Synchronous processing requires more resources | ||
| - Discuss with Altinn about the pricing model for your use case |
There was a problem hiding this comment.
Not sure about this section.
| 1. **Immediate delivery** - the user receives the code while waiting | ||
| 2. **Time-to-live control** - the code is not sent if it has already expired | ||
| 3. **Idempotency** - prevents duplicate sends upon repeated clicks | ||
| 4. **Simple implementation** - synchronous API is easier to implement than asynchronous handling |
There was a problem hiding this comment.
The implementation will not change much for the service owner, there is still need for polling/status feed checks to track the status. For the use case of OTPs the argument can actually be made that the implementation is more involved.
| ## Next Steps | ||
|
|
||
| - Read the [instant messaging guide](/en/notifications/guides/instant-messaging/) to learn how to implement instant messaging in your service | ||
| - See the [API reference](/en/notifications/reference/api/) for a detailed description of the endpoints |
There was a problem hiding this comment.
"Explore for complete API documentation": maybe misleading, this page is mostly just an overview of how to authenticate.
2 participants
Related to Altinn/altinn-notifications#1071
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.