Contact flows

Use the capabilities endpoint to decide which protocol to use.

Check capabilities

curl -H 'Authorization: Bearer YOUR_API_KEY' \
  'https://backend.blooio.com/v2/api/contacts/%2B15551234567/capabilities'

Response example:

{
  "contact": "+15551234567",
  "type": "phone",
  "capabilities": { "imessage": true, "sms": true },
  "last_checked": 1703123457000
}

Send on the best channel

If imessage is true, prefer iMessage; otherwise send SMS. Blooio automatically selects the best protocol, but you can track which was used via webhooks.

import fetch from 'node-fetch'

async function sendBest(contact, text) {
  const encodedContact = encodeURIComponent(contact)
  
  // Check capabilities
  const capsRes = await fetch(`https://backend.blooio.com/v2/api/contacts/${encodedContact}/capabilities`, {
    headers: { 'Authorization': `Bearer ${process.env.BLOOIO_API_KEY}` }
  })
  const caps = await capsRes.json()
  const protocol = caps.capabilities?.imessage ? 'imessage' : 'sms'

  // Send the message
  const res = await fetch(`https://backend.blooio.com/v2/api/chats/${encodedContact}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BLOOIO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text, metadata: { expected_protocol: protocol } })
  })
  
  return res.json()
}

Store the expected protocol in metadata for downstream analytics.

Managing contacts

You can also create and manage contacts with the v2 API:

Create a contact

curl -X POST 'https://backend.blooio.com/v2/api/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifier": "+15551234567",
    "name": "John Doe"
  }'

Update a contact

curl -X PATCH 'https://backend.blooio.com/v2/api/contacts/%2B15551234567' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe"
  }'

List contacts

curl 'https://backend.blooio.com/v2/api/contacts?limit=50&sort=recent' \
  -H 'Authorization: Bearer YOUR_API_KEY'