# Integration Examples

Common Custom Action patterns and real-world AV integrations.

---

> **Note:** Custom Actions require a Builder plan or higher.
> [Upgrade to Builder](https://app.avcodex.com/plans)

## Slack notifications

Push status updates from the agent to a Slack channel via webhook. Useful for install-team standups, commissioning callouts, or escalations.

### Configuration

```bash
curl -X POST https://hooks.slack.com/services/{{var.SLACK_WEBHOOK_ID}} \
  -H "Content-Type: application/json" \
  -d '{
    "text": "{{message}}",
    "channel": "{{channel}}",
    "username": "AVCodex Bot"
  }'
```

### Parameters

| Parameter          | Source        | Configuration                  |
| ------------------ | ------------- | ------------------------------ |
| `message`          | AI Generated  | Message content to send.       |
| `channel`          | AI Generated  | Target channel (optional).     |
| `SLACK_WEBHOOK_ID` | Variable      | Your Slack webhook ID.         |

### Usage

_"Post to #av-ops that Boardroom 4 commissioning passed."_

## OpenAI completions

Call OpenAI's API for an extra round of analysis (for example, summarizing a long commissioning checklist).

### Configuration

```bash
curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer {{var.OPENAI_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": {{system.message_history}},
    "temperature": 0.7,
    "max_tokens": {{maxTokens}}
  }'
```

### Parameters

| Parameter         | Source             | Configuration                   |
| ----------------- | ------------------ | ------------------------------- |
| `OPENAI_API_KEY`  | Variable (secret)  | Your OpenAI API key.            |
| `message_history` | System variable    | Conversation context.           |
| `maxTokens`       | AI Generated       | Token limit (default: 1000).    |

## SendGrid email

Send a transactional email, for example a client-acceptance email after commissioning.

### Configuration

```bash
curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer {{var.SENDGRID_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{
      "to": [{"email": "{{recipientEmail}}"}],
      "subject": "{{subject}}"
    }],
    "from": {
      "email": "{{var.FROM_EMAIL}}",
      "name": "{{var.FROM_NAME}}"
    },
    "content": [{
      "type": "text/html",
      "value": "{{emailBody}}"
    }]
  }'
```

### Variables

```bash
SENDGRID_API_KEY = SG.abc123...
FROM_EMAIL = noreply@your-integrator.com
FROM_NAME = Your Integrator
```

## Google Sheets

Read or append to a Google Sheet. Common use: an asset register or a per-room commissioning log.

### Read data

```bash
curl -X GET "https://sheets.googleapis.com/v4/spreadsheets/{{var.SHEET_ID}}/values/{{range}}" \
  -H "Authorization: Bearer {{var.GOOGLE_API_KEY}}"
```

### Append data

```bash
curl -X POST "https://sheets.googleapis.com/v4/spreadsheets/{{var.SHEET_ID}}/values/{{range}}:append" \
  -H "Authorization: Bearer {{var.GOOGLE_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [[
      "{{system.timestamp}}",
      "{{system.user_id}}",
      "{{data}}"
    ]]
  }'
```

## Webhook with dependencies

Multi-step workflow using action dependencies. Example: register a new site, then push a welcome ticket to the field-service queue.

### Step 1: create site record

```bash
curl -X POST https://api.example.com/sites \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{var.API_KEY}}" \
  -d '{
    "name": "{{siteName}}",
    "client": "{{clientName}}"
  }'
```

Returns: `{"data": {"id": "site_123", "name": "1200 Market"}}`.

### Step 2: open kickoff ticket

Use the site ID from Step 1:

```bash
curl -X POST https://api.example.com/tickets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{var.API_KEY}}" \
  -d '{
    "site_id": "{{siteId}}",
    "template": "kickoff",
    "send_at": "{{system.timestamp}}"
  }'
```

**Parameter configuration for `site_id`:**

- Source: Output from another Action.
- Action: Create site record.
- JSONPath: `$.data.id`.

## CRM integration

Update client records in your CRM (HubSpot, Salesforce, ConnectWise).

### Configuration

```bash
curl -X PATCH https://api.crm.com/v2/contacts/{{contactId}} \
  -H "Authorization: Bearer {{var.CRM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "last_contact": "{{system.timestamp}}",
      "last_message": "{{summary}}",
      "status": "{{status}}"
    }
  }'
```

### AI instructions

For `summary`:

```
Summarize the key points of the conversation in 1-2 sentences. Mention any rooms, devices, or deadlines referenced.
```

For `status`:

```
Choose one: 'rfp-open', 'design-review', 'install-active', 'commissioning', 'closed-won', 'closed-lost'.
```

## Stripe payment

Create payment intents via Stripe, for example accepting a deposit on a hospitality AV refresh.

### Configuration

```bash
curl -X POST https://api.stripe.com/v1/payment_intents \
  -u "{{var.STRIPE_SECRET_KEY}}:" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "amount={{amount}}&currency=usd&customer={{customerId}}"
```

### Parameters

| Parameter           | Source             | Configuration              |
| ------------------- | ------------------ | -------------------------- |
| `STRIPE_SECRET_KEY` | Variable (secret)  | Your Stripe secret key.    |
| `amount`            | AI Generated       | Amount in cents.           |
| `customerId`        | AI Generated       | Stripe customer ID.        |

## Network monitoring lookup

Pull a device's recent status from a monitoring tool, for example checking a Q-SYS Core or a Crestron 4-Series before dispatching a tech.

### Configuration

```bash
curl -X GET "https://api.your-monitoring.com/devices/{{deviceId}}/status" \
  -H "Authorization: Bearer {{var.MONITORING_API_KEY}}"
```

### Usage examples

_"Is the Q-SYS Core in the auditorium online?"_
_"What was the last reboot time for the boardroom Crestron processor?"_

## GitHub integration

Open issues in a repo, for example a control-system code library where programmers track Crestron SIMPL or Q-SYS Lua modules.

### Configuration

```bash
curl -X POST https://api.github.com/repos/{{var.GITHUB_OWNER}}/{{var.GITHUB_REPO}}/issues \
  -H "Authorization: Bearer {{var.GITHUB_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "{{issueTitle}}",
    "body": "{{issueBody}}",
    "labels": {{labels}},
    "assignees": {{assignees}}
  }'
```

### Parameter configuration

| Parameter    | Source        | AI instructions                                                  |
| ------------ | ------------- | ---------------------------------------------------------------- |
| `issueTitle` | AI Generated  | Concise issue title that names the module and symptom.           |
| `issueBody`  | AI Generated  | Detailed description, include processor model and firmware.      |
| `labels`     | AI Generated  | Array of labels, for example ["crestron", "simpl", "bug"].       |
| `assignees`  | AI Generated  | Array of GitHub usernames to assign.                             |

## Best practices

### 1. Error handling

Always return clear error messages:

```json
{
  "success": false,
  "error": "API key invalid. Please check your credentials."
}
```

### 2. Rate limiting

Respect API rate limits:

- Add delays between requests.
- Implement exponential backoff.
- Cache responses when possible.

### 3. Security

- Use HTTPS endpoints only.
- Store credentials as secret variables.
- Never log sensitive data.
- Validate all inputs.

### 4. Performance

- Paginate large result sets.
- Use field selection to minimize data.
- Implement timeouts (30s max).
- Cache frequently accessed data.

### 5. Testing

- Test with various inputs.
- Verify error handling.
- Check edge cases.
- Monitor response times.

## Next steps

- [Getting Started](/docs/custom-actions/getting-started)
- [Parameter configuration](/docs/custom-actions/parameter-configuration)
- [Manage variables](/docs/custom-actions/variables-and-secrets)
- [Testing guide](/docs/custom-actions/testing-and-debugging)

*AVCodex · Your AV expertise. Amplified by AI.*