Podium Hello World

---
name: podium-hello-world
description: "Podium hello world \u2014 business messaging and communication platform\
  \ integration.\nUse when working with Podium API for messaging, reviews, or payments.\n\
  Trigger with phrases like \"podium hello world\", \"podium-hello-world\".\n"
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(curl:*), Grep
version: 2.0.0
license: MIT
tags:
- saas
- podium
- messaging
- reviews
- payments
compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
---
# Podium Hello World

## Overview
Send your first Podium message, list contacts, and check location details using the Podium REST API.

## Prerequisites
- Completed `podium-install-auth` setup with valid access token
- A Podium location ID

## Instructions

### Step 1: List Locations
```typescript
const { data } = await podium.get('/locations');
for (const loc of data.data) {
  console.log(`Location: ${loc.attributes.name} (ID: ${loc.id})`);
}
```

### Step 2: List Contacts
```typescript
const locationId = 'loc_xxxxx';
const { data } = await podium.get(`/locations/${locationId}/contacts`);
for (const contact of data.data) {
  console.log(`  ${contact.attributes.name} — ${contact.attributes.phone}`);
}
```

### Step 3: Send a Message
```typescript
// Messages are sent via the Podium platform to the customer's phone
const { data } = await podium.post(`/locations/${locationId}/messages`, {
  data: {
    attributes: {
      body: 'Hello from our integration! How can we help?',
      'contact-phone': '+15551234567',
    },
  },
});
console.log(`Message sent: ${data.data.id}`);
```

## Output
- Listed locations with IDs
- Retrieved contacts for a location
- Sent a test message via Podium

## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| `404 Location not found` | Wrong location ID | List locations first to get valid IDs |
| `422 Invalid phone` | Bad phone format | Use E.164 format: +15551234567 |
| `403 Forbidden` | Missing scope | Add `messages.write` scope to OAuth app |

## Resources
- [Podium API Reference](https://docs.podium.com/reference)
- [Sync Messages](https://docs.podium.com/docs/sync-messages-from-podium-conversations)

## Next Steps
Build messaging workflow: `podium-core-workflow-a`