Hane Platform

Email, AI calls, and notifications

Notifications in Communication, outbound contact by agents (email, SMS, AI calls), contact endpoints and stop requests, and sender identities.

This page explains Communication, the service Hane uses to contact people inside and outside the organization. It treats Workflow notifications and agents contacting outside parties by email, SMS, or phone separately.

Two kinds of contact

Kind	Who sends it	Approval
Notification	A Workflow `notify` step sends an email to a group in the organization, or a post to an internal chat channel	Not needed; recipients are inside the organization
Outbound contact	An agent calls `communication.send_email`, `communication.send_sms`, or `communication.place_call`	Always needed. Hane sends once, after the ActionRequest with fixed recipient and content is approved

A notification’s group is resolved to member email addresses right before sending. Read the sent records with GET /v1/communication/messages.

Contact endpoints

When an agent contacts someone outside, it never passes a number or address directly. It passes the ID of a contact endpoint (ContactEndpoint) and the purpose of the contact.

A contact endpoint holds either a phone number or an email address, along with allowed contact purposes, whether AI calls are allowed, where it came from, and a validity period (POST /v1/communication/contacts).
The value is encrypted with a key per contact endpoint. Lists and approval screens show only a masked value (the last four digits for numbers).
Seeing the full value requires communication:contacts.reveal, and every reveal is recorded in the audit log.
Agents cannot propose or perform contact with an unverified endpoint. A person either records that they confirmed it with the owner (verify), or sends a fixed message with a confirmation code and enters the code the owner reads back (verification-challenges). Endpoints imported from a connection come from the source of truth and need no verification.

Contact policies

A ContactPolicy in communication/v1alpha1 sets, for each contact purpose, the allowed channels, contact hours, and the number of and interval between attempts.

apiVersion: communication/v1alpha1
kind: ContactPolicy
metadata:
  name: quote-request
spec:
  purpose: Request a quote
  channels: [email]
  hours: { from: "09:00", to: "18:00", timezone: Asia/Tokyo, days: [mon, tue, wed, thu, fri], holidays: jp }
  maxAttempts: 3

The state of the contact endpoint and these rules are checked again at execution time, after approval.

Stop requests

When someone asks not to be contacted again, Hane records the number or address in the stop ledger. No call, SMS, or email goes to a value in the ledger, even from another contact endpoint registered with the same value. Actions approved before the request also fail right before sending.

When the callee declines during an AI call, Hane records it automatically.
A person records it with POST /v1/communication/contacts/{id}/stop.
Only an administrator can lift it (resume), with a reason, and only after the person has consented again.

The stop ledger keeps a keyed hash of the value so it can still match after the contact endpoint is deleted.

Sender identities

A SenderIdentity in communication/v1alpha1 holds the company name, sender address, caller number, an “on behalf of” line, and a signature. When an agent definition names it in sender, messages go out under that identity.

An identity cannot be used until an administrator reviews and approves it (POST /v1/communication/senders/{name}/approve, which requires communication:senders.approve). Approval is tied to the content’s digest, so changing the content requires approval again. Only verified sender domains and caller numbers can be used.

AI calls Preview

An AI call is a phone call, made only after approval, in which a conversation agent talks to the callee strictly within a call brief (CallBrief).

A business agent fills a CallBriefTemplate with facts to create the call brief, which is fixed in the ActionRequest by digest. The approver sees exactly what will be said.
Every call opens by giving the caller’s name, stating that it is an AI, that the call is recorded, and that the callee can ask not to be called again.
The conversation agent only says sentences built from the call brief, or confirmations that repeat the callee’s answers. It never says forbidden words.
Hane returns a transcript and an answer per item. What the callee says comes from outside and is never treated as an instruction.

Today, calls are verified on a local line without audio. Connecting to real phone lines and a speech model comes later.

Receiving replies

Email sent by an agent carries a signed Message-ID. When a reply arrives, Hane uses that signature to determine the organization, project, and original action, records the reply, and moves forward any case waiting for it (GET /v1/communication/inbound). The reply body is kept as untrusted input.

Deleting and keeping

Deleting a contact endpoint deletes the value and any records the value was copied into (transcripts, replies, cases, agent runs and conversations), keeping only the masked value and the records. Nothing is deleted while a hold is in place. If you set days in ContactRetention, Hane automatically deletes values of expired contact endpoints.

Next steps