Communications

This page documents the current outbound communication behavior used by the API.

Invoice Email Provider

Invoice emails and patient import invitation emails are sent through Resend.

Runtime wiring:

• cmd/main.go creates services.NewResendEmailService(cfg).
• The router stores it as EmailSender.
• Invoice send flows call rctx.EmailSender.SendInvoice(...).
• Patient import invitation flows call SendPatientInvitation(...) when the configured email sender supports it.
• services/resend.go sends a POST request to the Resend /emails API.

Configuration:

Invoice Email Flow

Invoice emails are generated with a PDF attachment and sent through Resend.

Manual invoice email flow:

1. Call invoices/send-email.
2. Backend loads the invoice, organization, and patient.
3. Backend renders the invoice PDF.
4. Backend calls EmailSender.SendInvoice.
5. Resend sends the email with the PDF attachment.
6. Backend updates emailedAt on the invoice after a successful send.

Automatic invoice email flow after successful payment:

1. The payment success endpoint creates or updates the payment.
2. Backend calls payments/common.SendInvoiceForPayment.
3. Backend creates a paid invoice for the payment source when needed.
4. Backend calls invoices/send-email.
5. The invoice is delivered through Resend.

Automatic invoice sending is used by these current success flows:

Patient Import Invitation Flow

Patient import invitation emails are sent after patientProfiles/importRecords successfully creates or updates an imported patient profile with an email address.

Flow:

1. Backend validates that the doctorId belongs to the organizationId.
2. Backend creates or updates each imported patient profile.
3. For each successfully created or updated patient with an email address, backend attempts one invitation email per unique email in the import batch.
4. The email subject says that the importing doctor is available on Aivida.
5. The email body tells the patient that the doctor added their details to Aivida and is available there for healthcare needs.

This email is best-effort. If the email sender is not configured, does not support patient invitations, or Resend returns an error, the import response is still returned and the failure is logged.

Module-Based Notifications

Use the notifications namespace for in-app notification records and module-based communication routing. The frontend can send module to group notifications by product area, for example appointments, providerOrders, labOrders, billing, or hrmPayroll.

module is a frontend-friendly alias for relatedEntityType. If both module and relatedEntityType are sent, relatedEntityType wins.

Supported Notification Channels

The notifications.create API records the communication intent and delivery metadata. Push/SMS delivery workers or provider integrations can use channels, recipientStackUserId, module, relatedEntityId, and dedupeKey to process and update delivery state.

Create Appointment Push Notification

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "notifications",
  "apiName": "create",
  "data": {
    "organizationId": "org_123",
    "recipientStackUserId": "patient_stack_user_123",
    "recipientRole": "patient",
    "type": "appointment_reminder",
    "title": "Appointment reminder",
    "message": "Your appointment starts in 15 minutes.",
    "module": "appointments",
    "relatedEntityId": "appointment_123",
    "channels": ["push", "in_app"],
    "navigationTarget": "appointment_details",
    "navigationParams": {
      "appointmentId": "appointment_123"
    },
    "deliveryState": "PENDING",
    "dedupeKey": "appointment_123:reminder_15m"
  }
}'

Create Appointment SMS Notification

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "notifications",
  "apiName": "create",
  "data": {
    "organizationId": "org_123",
    "recipientStackUserId": "patient_stack_user_123",
    "recipientRole": "patient",
    "type": "appointment_sms_reminder",
    "title": "Appointment SMS reminder",
    "message": "Reminder: your Aivida appointment is scheduled for 10:30 AM.",
    "module": "appointments",
    "relatedEntityId": "appointment_123",
    "channels": ["sms"],
    "deliveryState": "PENDING",
    "dedupeKey": "appointment_123:sms_reminder"
  }
}'

List Notifications by Module

Use module when the app needs a module-specific notification center, for example only appointment notifications.

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "notifications",
  "apiName": "listByOrganization",
  "data": {
    "organizationId": "org_123",
    "module": "appointments",
    "page": 1,
    "pageSize": 20
  }
}'

Without module, notifications.listByOrganization returns all organization notifications.

Appointment Module Communication

Appointment communications are sent from the appointment APIs and the scheduled reminder worker. All appointment push notification records use relatedEntityType: "appointment" and navigate to appointment_detail.

Current Appointment Scenarios

Appointment Reminder Schedule

The reminder service schedules these jobs when an appointment has a valid patient stackUserId, valid date/time, and is not cancelled:

Reminder timing uses APPOINTMENT_TIMEZONE; default is Asia/Kolkata. If a reminder time is already in the past when the job is created, it is scheduled for the current time. The scheduler polls once per minute, claims up to 100 due notifications per poll, and retries failed scheduled notifications up to 3 times.

When an appointment is cancelled, pending scheduled reminders for that appointment are cancelled. When appointment date, time, or duration changes, pending reminders are cancelled and recreated for the new appointment time.

Appointment SMS Templates

SMS is sent through Airtel when AIRTEL_CUSTOMER_ID, AIRTEL_ENTITY_ID, AIRTEL_SOURCE_ADDRESS, an applicable DLT template ID, and a valid Indian mobile number are available. AIRTEL_AUTHORIZATION or AIRTEL_AUTH_TOKEN is used when configured.

Appointment Push and Email Rules

Push delivery uses active push devices from pushDevices plus the patient’s saved Expo token where available. If no push token exists, the notification row is still created and delivery is marked skipped.

Push providers are Expo and Firebase through the default push provider. Email uses Resend and is best-effort; when Resend credentials or recipient email are missing, the backend skips email and logs the reason.

Current appointment email coverage is:

There is currently no separate patient email for plain appointment created, confirmed status update, or cancelled status update.

Update Delivery State

After a push or SMS provider attempt, update the notification row with the delivery outcome.

curl -X POST https://api.aivida.in/api \
  -H "Content-Type: application/json" \
  -H "x-stack-access-token: <access_token_optional>" \
  -d '{
  "namespace": "notifications",
  "apiName": "update",
  "data": {
    "id": "notification_123",
    "organizationId": "org_123",
    "module": "appointments",
    "deliveryState": "SENT",
    "pushTicketIds": ["expo_ticket_123"]
  }
}'

For failed SMS or push attempts, send deliveryState: "FAILED" and put the provider error in deliveryError.

Failure Behavior

Payment confirmation is not rolled back only because invoice email delivery fails in the cart flow. Other payment paths log invoice delivery failures and continue according to the endpoint flow. Patient import invitation delivery failures are logged and do not fail the import. Resend configuration problems return errors such as missing API key, missing from email, empty recipient email, or empty PDF attachment.

Related APIs

• invoices/send-email: sends an existing invoice email.
• providerOrders/markPaymentSuccess: confirms provider-order payment and can trigger invoice email.
• appointments/markPaymentSuccess: confirms appointment payment and can trigger invoice email.
• cart/payment-success: confirms cart checkout payment and can trigger invoice email.
• patientProfiles/importRecords: imports patient records and can trigger patient invitation email.
• notifications/create: creates in-app, push, or SMS notification records with module grouping.
• notifications/listByOrganization: lists all organization notifications or filters by module.
• notifications/update: updates delivery state, push tickets, read/open state, or provider errors.
• pushDevices/*: manages Expo push tokens used by push notification delivery.