Communications

Internal only

This document contains protected Ikamet operational intelligence. Access restricted to Ikamet team via Cloudflare Access.

Communication types

Type	Channel	Direction
WHATSAPP	WhatsApp Cloud API	Inbound / Outbound
EMAIL	SendGrid	Outbound; Inbound (webhook)
SMS	Twilio	Outbound
INTERNAL_NOTE	System only	Internal
CALL_LOG	Manual entry	Internal

Core principle

Every customer interaction is logged. Whether a WhatsApp message comes in, an email is sent, or a staff member makes a call and logs a note — it all lands in the Communication table and appears in the customer’s communications tab.

WhatsApp (primary channel)

WhatsApp is the primary communication channel for Ikamet customers. Most customers in the target demographic (expatriates, international families) use WhatsApp as their main messaging app.

Inbound messages

Inbound WhatsApp messages are received via the WhatsApp Cloud API webhook. The webhook handler:

1. Receives the message payload
2. Looks up the customer by phone number
3. Calls logCommunication() with direction: INBOUND
4. Writes a COMMUNICATION_RECEIVED timeline event
5. Increments the unread count for the customer

Outbound messages

Outbound messages are sent from the customer workspace or triggered by automations:

POST /ops/customers/:id/communications
{
  "type": "WHATSAPP",
  "direction": "OUTBOUND",
  "body": "Your residence permit has been approved..."
}

Internal notes

Internal notes are private — visible only to Ikamet staff, not to customers. They are the primary tool for staff to document context, decisions, and next steps.

POST /ops/customers/:id/notes
{
  "body": "Customer called, confirmed bank statement is ready. Requested appointment booking."
}

Notes appear in the communications tab with an amber styling and italic text to distinguish them from customer-facing messages.

Unread tracking

Inbound messages from customers are marked as unread on arrival. The customer workspace header shows an unread count badge. Marks all as read via:

PATCH /ops/customers/:id/communications/read

Communication filters

In the customer workspace communications tab, staff can filter by:

• All
• WhatsApp
• Email
• Notes

In the global communications queue (coming soon), staff can filter by type, direction, and unread status across all customers.

Call logging

When a staff member calls a customer, they log the call after completion:

POST /ops/customers/:id/communications
{
  "type": "CALL_LOG",
  "direction": "INTERNAL",
  "subject": "Renewal discussion",
  "body": "Spoke to customer re: upcoming permit renewal. Customer confirmed they will be in Turkey. Booked appointment for June 15."
}

Privacy and retention

• All communication content is stored in the Ikamet database (DigitalOcean PostgreSQL)
• No communication content is shared with third parties except as required for delivery (e.g., WhatsApp message body sent to Meta for delivery)
• Communication records are retained per the Ikamet data retention policy