Sending Messages

Outbound messages use the existing POST /api/messaging/send endpoint. Two new match arms handle FacebookMessenger and InstagramDm channels.

Send Flow

1. Query organization_meta_settings for the page access token
2. Resolve the recipient’s platform ID (contact_facebook or contact_instagram)
3. Send text via Graph API, then each attachment as a separate message
4. Store the outbound message record with external_id from Meta’s response
5. Publish via WebSocket

Graph API Calls

Facebook Messenger

Text and attachments go through /me/messages:

// Text message
POST https://graph.facebook.com/v21.0/me/messages
{
  "recipient": { "id": "<PSID>" },
  "message": { "text": "Hello!" },
  "messaging_type": "RESPONSE"
}

// Attachment
POST https://graph.facebook.com/v21.0/me/messages
{
  "recipient": { "id": "<PSID>" },
  "message": {
    "attachment": {
      "type": "image",
      "payload": { "url": "<public_url>", "is_reusable": false }
    }
  },
  "messaging_type": "RESPONSE"
}

Instagram DM

Instagram uses /{ig_account_id}/messages instead of /me/messages. The payload structure is identical.

Attachment Handling

Meta allows one attachment per message. When you send multiple attachments, the service loops and sends each as a separate Graph API call.

MIME type mapping:

MIME prefix	Meta type
image/*	"image"
video/*	"video"
audio/*	"audio"
Everything else	"file"

Attachments are pre-uploaded to storage. The service generates presigned public URLs via resolve_meta_attachment_urls before sending.

Error Handling

Condition	Error message
No Meta settings for org	”Facebook Messenger is not connected. Connect via Settings > Integrations.”
No PSID for contact (Messenger)	“This contact has no Facebook Messenger ID. They must message your Page first.”
No IGSID for contact (Instagram)	“This contact has no Instagram ID. They must message your account first.”
No IG account linked	”No Instagram account linked. Connect an Instagram Business account via Settings > Integrations.”
Graph API error 190 (token expired)	“Meta connection has expired. Please reconnect via Settings > Integrations.”

Service Functions

In meta_send_service.rs:

Function	Description
send_messenger_message(token, psid, text)	Send text via Messenger
send_messenger_attachment(token, psid, type, url)	Send attachment via Messenger
send_instagram_message(ig_id, token, igsid, text)	Send text via Instagram DM
send_instagram_attachment(ig_id, token, igsid, type, url)	Send attachment via Instagram DM

All functions return the Meta-assigned message ID on success.