Phonebook & Messages

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

PBAP (Phonebook Access Profile) and MAP (Message Access Profile) let you read contacts and messages from paired phones.

Prerequisites

These profiles use OBEX. Ensure obexd is installed:

bt_obex_status

If not ready:

```bash sudo pacman -S bluez-obex ``` ```bash sudo apt install bluez-obex ```

Phonebook Access (PBAP)

Download Entire Phonebook

bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/contacts.vcf"

This downloads all contacts as a single vCard file.

List Contacts

bt_phonebook_list address="AA:BB:CC:DD:EE:FF"

Returns:

{
  "entries": [
    {"handle": "1.vcf", "name": "Alice Smith"},
    {"handle": "2.vcf", "name": "Bob Jones"},
    ...
  ],
  "count": 150
}

Get Single Contact

bt_phonebook_get address="..." handle="1.vcf" save_path="~/alice.vcf"

Search Contacts

# Search by name
bt_phonebook_search address="..." field="name" value="Smith"

# Search by phone number
bt_phonebook_search address="..." field="number" value="+1555"

Count Contacts

bt_phonebook_count address="AA:BB:CC:DD:EE:FF"

Returns total number of contacts without downloading them.

Phonebook Folders

PBAP provides access to different phonebook locations:

Folder	Contents
`telecom/pb`	Main phonebook (default)
`telecom/ich`	Incoming call history
`telecom/och`	Outgoing call history
`telecom/mch`	Missed call history
`telecom/cch`	Combined call history
`SIM1/telecom/pb`	SIM card contacts

bt_phonebook_list address="..." folder="telecom/ich"

Message Access (MAP)

List Message Folders

bt_messages_folders address="AA:BB:CC:DD:EE:FF"

Returns:

{
  "folders": [
    {"name": "inbox"},
    {"name": "sent"},
    {"name": "drafts"},
    {"name": "outbox"},
    {"name": "deleted"}
  ]
}

List Messages

# All inbox messages
bt_messages_list address="..." folder="inbox"

# Unread only
bt_messages_list address="..." folder="inbox" unread_only=true

# Limit results
bt_messages_list address="..." folder="inbox" max_count=50

Returns:

{
  "messages": [
    {
      "handle": "msg001",
      "subject": "Meeting tomorrow",
      "sender": "+15551234567",
      "timestamp": "2024-01-15T10:30:00",
      "read": false,
      "type": "SMS"
    }
  ]
}

Download Message

bt_messages_get address="..." handle="msg001" save_path="~/message.txt"

Send Message

bt_messages_send address="..." recipient="+15559876543" message="Hello from mcbluetooth!"

Common Workflows

Backup All Contacts

# Download as vCard (can import into any contact app)
bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/phone_backup_$(date +%Y%m%d).vcf"

Export Call History

# Get incoming calls
bt_phonebook_list address="..." folder="telecom/ich"

# Get missed calls
bt_phonebook_list address="..." folder="telecom/mch"

Find Contact by Phone Number

bt_phonebook_search address="..." field="number" value="555-1234"

Archive Text Messages

# List all sent messages
bt_messages_list address="..." folder="sent"

# Download specific message
bt_messages_get address="..." handle="msg042" save_path="~/messages/msg042.txt"

Device Compatibility

PBAP Support

Device	Support
Android phones	✓ Full
iPhones	✓ Full (when paired)
Feature phones	✓ Usually
Car systems	✓ Often (receive only)

MAP Support

Device	Read	Send
Android	✓	Varies
iPhone	✗	✗
Feature phones	Varies	Varies

Troubleshooting

”NotAuthorized” Error

The phone is blocking access. Check:

Phone screen for permission prompt
Bluetooth settings → paired device → enable phonebook/message access

Empty Phonebook

Some phones require explicit permission:

Android: Settings → Apps → Bluetooth → Permissions → Contacts
iPhone: Settings → Bluetooth → [device] → Allow Contact Access

MAP Connection Fails

Verify device supports MAP: bt_device_info adapter="hci0" address="..."
Check for MAP UUID in the UUIDs list
Some devices need MAP enabled in Bluetooth settings

Slow Downloads

Large phonebooks (1000+ contacts) take time:

PBAP downloads are sequential
Consider using bt_phonebook_count first to estimate
vCard format is verbose

Privacy Considerations

Phonebook and message access requires active pairing
Devices typically prompt for permission on first access
Permission can be revoked on the phone at any time