API Reference

Send an end-to-end encrypted text message to a recipient.

Request Body

Parameter	Type	Description
torequired	string	Recipient phone hash or Aurogy ID
textrequired	string	Message body (max 4,096 characters)
reply_tooptional	string	Message ID to reply to
metadataoptional	object	Custom key-value pairs (max 10 keys, 256 chars each)

Request

{
  "to": "auro_usr_8f3k29d1a7",
  "text": "Your order #4821 has been shipped!",
  "metadata": {
    "order_id": "4821",
    "type": "shipping_notification"
  }
}

Response

200 Message accepted

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "queued",
  "to": "auro_usr_8f3k29d1a7",
  "created_at": "2026-04-13T14:30:00Z"
}

Send an encrypted media message. The file is encrypted client-side, uploaded to IPFS, and the encrypted reference is delivered to the recipient.

Request Body

Parameter	Type	Description
torequired	string	Recipient phone hash or Aurogy ID
media_urlrequired	string	URL of the media file to send (HTTPS only)
media_typerequired	string	MIME type: image/jpeg, image/png, video/mp4, audio/ogg, application/pdf
captionoptional	string	Caption text (max 1,024 characters)
filenameoptional	string	Display filename for documents

Request

{
  "to": "auro_usr_8f3k29d1a7",
  "media_url": "https://cdn.example.com/invoice-4821.pdf",
  "media_type": "application/pdf",
  "caption": "Invoice for order #4821",
  "filename": "invoice-4821.pdf"
}

Response

200 Message accepted

{
  "id": "msg_f6e5d4c3b2a1",
  "status": "queued",
  "to": "auro_usr_8f3k29d1a7",
  "media_cid": "bafybeigdyrzt5sfp7...",
  "created_at": "2026-04-13T14:32:00Z"
}

Send a pre-approved template message. Templates must be created and approved in the Business Dashboard before use.

Request Body

Parameter	Type	Description
torequired	string	Recipient phone hash or Aurogy ID
templaterequired	string	Template name (e.g., order_confirmation)
languagerequired	string	Template language code (e.g., en)
variablesoptional	object	Key-value pairs for template placeholders

Request

{
  "to": "auro_usr_8f3k29d1a7",
  "template": "order_confirmation",
  "language": "en",
  "variables": {
    "customer_name": "Alex",
    "order_id": "4821",
    "delivery_date": "April 18, 2026"
  }
}

Response

200 Message accepted

{
  "id": "msg_t1e2m3p4l5a6",
  "status": "queued",
  "to": "auro_usr_8f3k29d1a7",
  "template": "order_confirmation",
  "created_at": "2026-04-13T14:35:00Z"
}

Retrieve the delivery status of a previously sent message.

Path Parameters

Parameter	Type	Description
message_idrequired	string	The message ID returned from a send request

Response

200 Message found

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "delivered",
  "to": "auro_usr_8f3k29d1a7",
  "created_at": "2026-04-13T14:30:00Z",
  "delivered_at": "2026-04-13T14:30:02Z",
  "read_at": null
}

Possible status values: queued, sent, delivered, read, failed

List all conversations for your business account, ordered by most recent activity.

Query Parameters

Parameter	Type	Description
limitoptional	integer	Number of results (default: 20, max: 100)
cursoroptional	string	Pagination cursor from previous response
statusoptional	string	Filter: active, archived, all

Response

200 Conversations list

{
  "conversations": [
    {
      "id": "conv_x1y2z3",
      "participant": "auro_usr_8f3k29d1a7",
      "last_message_at": "2026-04-13T14:30:02Z",
      "unread_count": 3,
      "status": "active"
    }
  ],
  "next_cursor": "eyJsYXN0X2lkIjoiY29udl94...",
  "has_more": true
}

Retrieve your business profile information.

Response

200 Profile data

{
  "id": "biz_a1b2c3d4",
  "name": "Acme Corp",
  "description": "Premium widgets and gadgets",
  "avatar_url": "https://api.aurogy.com/v1/profile/avatar",
  "verified": true,
  "created_at": "2026-01-15T09:00:00Z"
}

Update your business profile. Only include fields you want to change.

Request Body

Parameter	Type	Description
nameoptional	string	Business display name (max 128 chars)
descriptionoptional	string	Business description (max 512 chars)
avatar_urloptional	string	URL to new avatar image (HTTPS, max 5MB)

Response

200 Profile updated

{
  "id": "biz_a1b2c3d4",
  "name": "Acme Corp",
  "description": "Premium widgets, gadgets, and more",
  "updated_at": "2026-04-13T15:00:00Z"
}