---
title: Phonebook & Messages
description: Access contacts and SMS using PBAP and MAP profiles
---

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.

<Aside type="note">
Both profiles require the device to be paired first. See [Device Pairing](/guides/pairing/).
</Aside>

## Prerequisites

These profiles use OBEX. Ensure obexd is installed:

```
bt_obex_status
```

If not ready:

<Tabs>
  <TabItem label="Arch Linux">
```bash
sudo pacman -S bluez-obex
```
  </TabItem>
  <TabItem label="Debian/Ubuntu">
```bash
sudo apt install bluez-obex
```
  </TabItem>
</Tabs>

## 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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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

<Aside type="caution">
Message sending support varies by device. Many phones only allow read access.
</Aside>

```
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 |

<Aside type="note">
iPhone doesn't support MAP. Use iCloud or other sync methods for messages.
</Aside>

## Troubleshooting

### "NotAuthorized" Error

The phone is blocking access. Check:
1. Phone screen for permission prompt
2. 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

1. Verify device supports MAP: `bt_device_info adapter="hci0" address="..."`
2. Check for MAP UUID in the UUIDs list
3. 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

<Aside type="caution">
These tools access personal data. Use responsibly and only on devices you own or have explicit permission to access.
</Aside>

- 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