Zapier Integration API Reference

The AssistLoop API is specifically designed to integrate seamlessly with Zapier, enabling you to build powerful automation workflows without writing code. Our API follows REST principles with predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and OAuth 2.0 authentication.

Base URL

https://api.assistloop.ai/api/v1

Authentication

The AssistLoop Zapier integration uses OAuth 2.0 for secure authentication. When you connect AssistLoop to Zapier, you'll be prompted to authorize the connection through a secure OAuth flow. Zapier will automatically handle token management, including automatic token refresh when needed.

Authorization: Bearer YOUR_ACCESS_TOKEN

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Example Request with Authentication

curl https://api.assistloop.ai/api/v1/oauth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

OAuth 2.0 Authorization Flow

AssistLoop uses OAuth 2.0 to securely connect with Zapier. This section describes the technical details of how Zapier obtains and refreshes access tokens when you connect your AssistLoop account.

OAuth 2.0 Endpoints

Available Scopes

Step 1: Authorization Request

When you click "Connect an Account" in Zapier, Zapier directs you to AssistLoop's authorization page. Behind the scenes, Zapier sends this authorization request:

Endpoint: POST /api/v1/oauth/authorize

Request Parameters

Example Request

curl -X POST https://api.assistloop.ai/api/v1/oauth/authorize \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "client_id": "your-client-id",
    "redirect_uri": "https://zapier.com/dashboard/auth/oauth/return/App1234CLIAPI/",
    "scope": "read:conversations read:messages manage:webhooks",
    "state": "random-state-string",
    "approved": true
  }'

Response

{
  "success": true,
  "code": "def50200a1b2c3...",
  "state": "random-state-string",
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

The code is the authorization code that should be exchanged for an access token in the next step.

Step 2: Exchange Authorization Code for Access Token

After you approve the connection, Zapier automatically exchanges the authorization code for an access token using the /oauth/token endpoint.

Endpoint: POST /oauth/token

Request Parameters (Authorization Code Grant)

Example Request

curl -X POST https://api.assistloop.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "redirect_uri": "https://zapier.com/dashboard/auth/oauth/return/App1234CLIAPI/",
    "code": "def50200a1b2c3..."
  }'

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "def50200d4e5f6..."
}

Step 3: Using the Access Token

Zapier automatically includes the access token in all API requests it makes on your behalf:

curl https://api.assistloop.ai/api/v1/oauth/me \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

Step 4: Automatic Token Refresh

When your access token expires (after 1 year), Zapier automatically uses the refresh token to obtain a new access token without requiring you to re-authorize. This happens seamlessly in the background.

Endpoint: POST /oauth/token

Request Parameters (Refresh Token Grant)

Example Request

curl -X POST https://api.assistloop.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "def50200d4e5f6...",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "def50200g7h8i9..."
}

OAuth 2.0 Security Best Practices

Errors

AssistLoop uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a resource was not found, etc.). Codes in the 5xx range indicate an error with AssistLoop's servers (these are rare).

HTTP Status Code Summary

Error Response Format

{
  "error": "Conversation not found",
  "message": "The requested conversation could not be found or you don't have access to it."
}

OAuth Endpoints

Get Current User

Retrieves information about the currently authenticated user. Use this endpoint to verify your authentication token and get details about the associated account.

Endpoint: GET /oauth/me

Example Request

curl https://api.assistloop.ai/api/v1/oauth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "uuid": "usr_abc123",
  "name": "John Doe",
  "email": "[email protected]"
}

Webhook Endpoints (Zapier Triggers)

Webhooks power Zapier triggers for your AssistLoop account. When you set up a trigger in Zapier (like "New Conversation" or "Human Handoff Required"), Zapier automatically subscribes to the appropriate webhook endpoint. When the event occurs in AssistLoop, we instantly notify Zapier to trigger your Zap.

Subscribe to Webhooks

Creates a new webhook subscription for Zapier triggers. When you enable a trigger in Zapier, Zapier automatically calls this endpoint to subscribe to events. When the event occurs in AssistLoop, we send the data to Zapier to trigger your Zap.

Endpoint: POST /webhooks/subscribe

Request Parameters

Example Request

curl -X POST https://api.assistloop.ai/api/v1/webhooks/subscribe \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_uuid": "org_xyz789",
    "agent_uuid": "agt_abc123",
    "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "event": "new_conversation",
    "platform": "zapier"
  }'

Response

{
  "data": {
    "id": "whk_xyz789",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  },
  "message": "Webhook subscribed successfully"
}

Webhook Event Types (Zapier Triggers)

These are the available triggers you can use in your Zapier workflows:

Webhook Payload Examples

New Conversation Event

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "new_conversation",
  "timestamp": "2025-01-20T16:00:00+00:00",
  "data": {
    "conversation": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "status": true,
      "response_mode": "ai",
      "created_at": "2025-01-20T16:00:00+00:00"
    },
    "agent": {
      "uuid": "agt_abc123",
      "name": "Customer Support Agent"
    },
    "chat_user": {
      "name": "Jane Smith",
      "email": "[email protected]"
    },
    "organization": {
      "uuid": "org_xyz789",
      "name": "Acme Corporation"
    },
    "initial_message": {
      "uuid": "msg_abc123",
      "content": "Hi, I need help with my order",
      "type": "guest",
      "created_at": "2025-01-20T16:00:00+00:00"
    }
  }
}

Human Handoff Required Event

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "human_handoff_required",
  "timestamp": "2025-01-20T16:05:00+00:00",
  "data": {
    "conversation": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "status": true,
      "response_mode": "human",
      "created_at": "2025-01-20T16:00:00+00:00"
    },
    "agent": {
      "uuid": "agt_abc123",
      "name": "Customer Support Agent"
    },
    "chat_user": {
      "name": "Jane Smith",
      "email": "[email protected]"
    },
    "organization": {
      "uuid": "org_xyz789",
      "name": "Acme Corporation"
    },
    "last_message": {
      "uuid": "msg_def456",
      "content": "I need to speak with a human agent",
      "type": "guest",
      "created_at": "2025-01-20T16:05:00+00:00"
    }
  }
}

Unsubscribe from Webhooks

Removes a webhook subscription. Zapier automatically calls this endpoint when you turn off or delete a trigger.

Endpoint: DELETE /webhooks/unsubscribe/{uuid}

Path Parameters

Example Request

curl -X DELETE https://api.assistloop.ai/api/v1/webhooks/unsubscribe/whk_xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "data": null,
  "message": "Webhook unsubscribed successfully"
}

Conversation Endpoints (Zapier Actions)

List Conversations

Use this action in Zapier to find and filter conversations. Perfect for building workflows that need to check conversation status, find conversations by date, or feed conversation data into other apps.

Endpoint: GET /automation/agents/{agentUuid}/conversations/list

Path Parameters

Query Parameters

Example Request

curl "https://api.assistloop.ai/api/v1/automation/agents/agt_abc123/conversations/list?status=1&response_mode=ai&per_page=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

The endpoint returns a direct array of conversation objects (not wrapped in a data field).

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess_abc123",
    "response_mode": "ai",
    "status": true,
    "last_message_seen": false,
    "deleted_at": null,
    "chat_user": {
      "name": "Jane Smith",
      "email": "[email protected]",
      "country_code": "US",
      "chat_user_id": "chu_xyz123"
    }
  }
]

Get Recent Conversation Samples

Provides sample data when you're setting up a Zapier trigger. When you click "Test Trigger" in Zapier, this endpoint returns recent conversations so you can see what data your Zap will receive.

Endpoint: GET /automation/agents/{agentUuid}/conversations/recent-sample

Path Parameters

Query Parameters

Example Request

curl "https://api.assistloop.ai/api/v1/automation/agents/agt_abc123/conversations/recent-sample?limit=3&type=new_conversation" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Returns an array of webhook payload samples in the same format as actual webhook deliveries.

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "event": "new_conversation",
    "timestamp": "2025-01-20T15:30:00+00:00",
    "data": {
      "conversation": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "status": true,
        "response_mode": "ai",
        "created_at": "2025-01-20T15:30:00+00:00"
      },
      "agent": {
        "uuid": "agt_abc123",
        "name": "Customer Support Agent"
      },
      "chat_user": {
        "name": "Sample Customer",
        "email": "[email protected]"
      },
      "organization": {
        "uuid": "org_xyz789",
        "name": "Acme Corporation"
      },
      "initial_message": {
        "uuid": "msg_sample123",
        "content": "Hello, I have a question",
        "type": "guest",
        "created_at": "2025-01-20T15:30:00+00:00"
      }
    }
  }
]

Close Conversation

Use this Zapier action to automatically close conversations as part of your workflow. Great for marking conversations as complete after creating a help desk ticket, logging to your CRM, or after a certain amount of time.

Endpoint: POST /automation/conversations/{conversationUuid}/close

Path Parameters

Request Parameters

Example Request

curl -X POST https://api.assistloop.ai/api/v1/automation/conversations/550e8400-e29b-41d4-a716-446655440000/close \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "zapier"
  }'

Response

{
  "status": "conversation_closed",
  "platform": "zapier"
}

Message Endpoints (Zapier Actions)

Find Messages

Use this Zapier action to retrieve the full message history from a conversation. Perfect for including context when creating support tickets, logging conversations, or analyzing customer interactions.

Endpoint: GET /automation/conversations/{conversationUuid}/messages/find

Path Parameters

Query Parameters

Example Request

curl "https://api.assistloop.ai/api/v1/automation/conversations/550e8400-e29b-41d4-a716-446655440000/messages/find?per_page=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Returns a direct array of message objects, ordered by created_at descending (newest first).

[
  {
    "id": "msg_abc124",
    "uuid": "660e8400-e29b-41d4-a716-446655440002",
    "content": "I'd be happy to help you with your order. Could you provide your order number?",
    "type": "agent",
    "is_read": null,
    "status": null,
    "responder_type": "ai",
    "emailed_at": null,
    "email_seen": false,
    "email_opened_at": null,
    "via": "web",
    "created_at": "2025-01-20T16:00:15.000000Z",
    "user_feedback": null,
    "sender_name": "Customer Support Agent",
    "attachments": []
  },
  {
    "id": "msg_abc123",
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "content": "I need help with my order",
    "type": "guest",
    "is_read": null,
    "status": null,
    "responder_type": null,
    "emailed_at": null,
    "email_seen": false,
    "email_opened_at": null,
    "via": "web",
    "created_at": "2025-01-20T16:00:00.000000Z",
    "user_feedback": null,
    "sender_name": "Jane Smith",
    "attachments": []
  }
]

Reply to Conversation

Use this Zapier action to automatically send messages to customers in response to events in other apps. Messages are sent as if from a human support agent.

Endpoint: POST /automation/conversations/{conversationUuid}/reply

Path Parameters

Request Parameters

Example Request

curl -X POST https://api.assistloop.ai/api/v1/automation/conversations/550e8400-e29b-41d4-a716-446655440000/reply \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thank you for contacting us. A support agent will be with you shortly."
  }'

Response

{
  "status": "sent",
  "message_id": "msg_xyz789"
}

Common Zapier Use Cases

Use Case 1: Slack Notification for New Conversations

Scenario: Get instant Slack notifications when customers start conversations with your AI agent.

Zap Template: Use this Zap Template (coming soon)

Use Case 2: Auto-Create Zendesk Tickets on Human Handoff

Scenario: Automatically create a Zendesk ticket with full conversation context when AI needs human help.

Zap Template: Use this Zap Template (coming soon)

Use Case 3: Auto-Close Inactive Conversations

Scenario: Keep your conversation list clean by automatically closing conversations that haven't had activity for 24 hours.

Zap Template: Use this Zap Template (coming soon)

Use Case 4: Daily Conversation Report to Slack

Scenario: Get a daily digest of conversation metrics delivered to your team's Slack channel.

📊 Daily AssistLoop Report - March 15, 2025

✅ Total Conversations: 47
🤖 Handled by AI: 39 (83%)
👤 Required Human Help: 8 (17%)
📭 Currently Open: 5
✓ Closed: 42

🔗 View open conversations in dashboard

Zap Template: Use this Zap Template (coming soon)

Rate Limiting

To ensure reliable service for all Zapier users, we implement rate limits on API endpoints:

Best Practices for Zapier Workflows

Designing Efficient Zaps

Start with Triggers, Not Polls

• Use our webhook-based triggers (New Conversation, Human Handoff Required) instead of polling endpoints
• Webhook triggers are instant and don't count against your Zapier task limit
• Polling-based searches should only be used when building scheduled reports or cleanup workflows

Handle Multiple Results

• When using "Find Messages" or "List Conversations," remember these return arrays
• Use Zapier's Looping action to process multiple items
• Consider using Filters to narrow down results before looping

Error Handling in Zaps

• Add Filter steps to skip API calls when data is missing
• Use Zapier's Error Handling to continue workflows even if one step fails
• Set up Task History monitoring to catch and fix errors quickly

Optimizing API Calls

Reduce Unnecessary Calls

• Don't fetch full message history if you only need the most recent message
• Use pagination (per_page) wisely - start with 10-20 items, not 100
• Filter conversations by created_from date to avoid fetching old data

Rate Limit Considerations

• If processing many conversations, add a 1-2 second delay between Close Conversation actions
• For bulk operations, spread them across multiple scheduled Zaps
• Monitor your Task History for 429 errors - these indicate you're hitting rate limits

Data Handling Best Practices

Understanding Field Types

• Conversation Status: Boolean (true = open, false = closed). Use "1" in API filters, not "true"
• Response Mode: String (ai or human). Use this to route conversations differently
• Message Types: guest (customer), agent (AI/human). Filter to see only customer messages
• Timestamps: ISO 8601 format with timezone. Use Zapier's date formatter to convert

Handling Missing Data

• Customer email and name may be null for anonymous conversations
• Always check if fields exist before using them in actions
• Use Zapier's Formatter to set default values for missing fields

Working with Message Content

• Messages may contain line breaks - use Formatter to clean up if needed
• Check for attachments array - it may be empty
• User feedback field is usually null (only set if customer rated the response)

Security Recommendations

Protect Customer Data

• Don't log customer messages to public channels
• Be careful when sending conversation data to third-party apps
• Use Zapier's Privacy Mode in Task History for sensitive data

OAuth Token Management

• Never share your connected account access with others
• Reconnect your AssistLoop account if you suspect token compromise
• Zapier handles token refresh automatically - don't try to manually refresh

Webhook Security

• Zapier automatically validates webhook signatures
• Webhook URLs are unique and secret - don't share them
• If a webhook URL is compromised, delete and recreate the trigger

Zapier OAuth Configuration

When setting up your Zapier integration, use the following OAuth configuration:

OAuth Configuration Parameters

Zapier OAuth Settings

1. Grant Type: Authorization Code
2. Authorization Code Method: POST (JSON body)
3. Token Request Method: POST (JSON body)
4. Refresh Token Method: POST (JSON body)
5. Automatically Refresh: Yes

Test API Call

Configure Zapier's test API call to verify authentication:

• URL: https://api.assistloop.ai/api/v1/oauth/me
• Method: GET
• Expected Response: JSON with uuid, name, and email fields

Testing Your Integration

curl https://api.assistloop.ai/api/v1/oauth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "uuid": "usr_abc123",
  "name": "Your Name",
  "email": "[email protected]"
}

curl "https://api.assistloop.ai/api/v1/automation/agents/YOUR_AGENT_UUID/conversations/recent-sample?limit=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X POST https://api.assistloop.ai/api/v1/webhooks/subscribe \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_uuid": "YOUR_ORG_UUID",
    "agent_uuid": "YOUR_AGENT_UUID",
    "target_url": "https://webhook.site/your-unique-url",
    "event": "new_conversation",
    "platform": "zapier"
  }'

curl "https://api.assistloop.ai/api/v1/automation/agents/YOUR_AGENT_UUID/conversations/list?status=1&per_page=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Fetch messages
curl "https://api.assistloop.ai/api/v1/automation/conversations/CONVERSATION_UUID/messages/find?per_page=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Send a reply
curl -X POST https://api.assistloop.ai/api/v1/automation/conversations/CONVERSATION_UUID/reply \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is a test message from the API"
  }'

curl -X POST https://api.assistloop.ai/api/v1/automation/conversations/CONVERSATION_UUID/close \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "zapier"
  }'

Troubleshooting

Common Issues

Support

For questions about the API or help with your integration:

• Documentation: https://api.assistloop.ai/docs
• Support Email: [email protected]
• Dashboard: https://api.assistloop.ai/dashboard

When contacting support, please include:

• Your organization UUID
• Agent UUID (if applicable)
• Request ID (from response headers: Request-Id)
• Full error message and response body
• Steps to reproduce the issue
• Sample request (with sensitive data redacted)