Custom Workspace & Webhook Integration Guide
NOTE: To use the custom webhook integration feature, you'll need a solid understanding of how webhooks work and how to implement them correctly. If you're not familiar with this, we strongly recommend working with a developer to ensure everything is set up smoothly and functions as intended. 🚀
Previously, integrations were limited to GoHighLevel (GHL). With Custom Workspaces, you can now:
- Integrate myCRMSIM with any platform
- Send messages into myCRMSIM via webhook
- Receive message status updates via webhook
- Receive inbound messages (WhatsApp / iMessage / SMS)
- Assign SIMs, WhatsApp, iMessage or devices per workspace
Key Concepts
Workspace
A workspace represents one external system / client / integration. Each workspace has:
- Unique location_id
- Contact & message routing
- Assigned SIM / iMessage / WhatsApp devices
- One outbound + inbound webhook endpoint
Webhook
Your system exposes an HTTP endpoint (URL) where:
- We send inbound messages & status updates
- You send outbound messages to myCRMSIM
Step 1: Create a New Workspace
- Go to Admin Panel → Workspaces / Webhooks
2. Click ➕ Add Workspace
3. You will see the Add New Workspace modal
Workspace Fields
| Field | Description |
| Select Existing Workspace | (Optional) Clone an existing workspace configuration |
| Name | Workspace name (e.g. Client Name / App Name) |
| Address | Optional business address |
| Contact email for the workspace | |
| Phone Number | Default phone number (E.164 recommended) |
| URL | Your webhook base URL |
Step 2: Configure Webhook Headers (Optional)
If your webhook requires authentication or custom headers:
- Click ➕ Add Header
2. Enter:
- Header Key (e.g. Authorization)
- Header Value (e.g. Bearer YOUR_API_KEY)
You can add multiple headers. These headers will be included in all webhook calls made to your system.
Examples:
Authorization: Bearer sk_live_xxx
X-Client-ID: mycrm-client-01
Examples:
Authorization: Bearer sk_live_xxx
X-Client-ID: mycrm-client-01
Step 3: Save Workspace
Click Create Workspace.
Your workspace will now appear in the Workspaces / Webhooks list with:
- Location ID
- Webhook URL
- Actions (Edit / Delete / Instructions)
Step 4: Assign Workspace to Subaccount SIM
Once the workspace is created:
- Go to Subaccount SIM Page
2. Click on the "Connect Location"
3. Choose the Workspace you created and toggle On.
You will now see this newly created workspace on the subaccount SIM page in your active workspaces.
Assign one or more:
- SIM numbers
- WhatsApp devices
- iMessage devices
Step 5: Sending Messages TO myCRMSIM (Outbound from Your System)
Your system sends messages to myCRMSIM using the webhook API below.
API EndpointPOST https://r6bszuuso6.execute-api.ap-southeast-2.amazonaws.com/prod/webhook
This endpoint is common for all custom workspaces. The location_id inside the payload determines routing.
API EndpointPOST https://r6bszuuso6.execute-api.ap-southeast-2.amazonaws.com/prod/webhook
This endpoint is common for all custom workspaces. The location_id inside the payload determines routing.
Required Request Body
Field Definitions
| Field | Required | Description |
| location_id | ✅ | Custom workspace location ID |
| user_id | ✅ | User identifier from your system |
| phone | ✅ | Recipient phone number (E.164 format) |
| message | ✅ | Message text body |
| attachments | ❌ | Array of publicly accessible media URLs |
| message_id | ✅ | Message identifier generated by your system |
| channel | ✅ | imessage, whatsapp, sms, or rcs |
Notes
- message_id is mandatory and used for all future status updates
- Media URLs must be publicly accessible
- The selected channel must be assigned to the workspace device
Step 6: Message Status Updates (From myCRMSIM to You)
For every outbound message, myCRMSIM sends status updates to your configured webhook URL.
Status Update Payload
Status Values
The following status values are sent by myCRMSIM:
| Status | Meaning |
| SENT | Message sent successfully |
| DELIVERED | Message delivered to recipient |
| FAILED | Message delivery failed |
Step 7: Inbound Messages (Replies from End Users)
When an end user replies via SMS, WhatsApp, or iMessage, myCRMSIM forwards the inbound message to your webhook URL.
Inbound Message Payload
Field Definitions
| Field | Description |
| type | Always MESSAGE |
| location_id | Workspace identifier |
| phone | Sender phone number |
| message | Inbound message text |
| isMe | Always false for inbound messages |
| attachments | Array of media URLs (if any) |
Step 8: Editing or Deleting a Workspace
From Workspaces / Webhooks page:
- Edit → Update workspace info, webhook URL, or headers
Delete → Permanently remove workspace (messages will stop)
⚠️ Deleting a workspace will break all assigned subaccounts.
Common Use Cases
- Custom CRM integration
- SaaS messaging backend
- AI / Bot platform
- Marketing automation tools
- Appointment systems
HTTP Responses & Error Handling
Your webhook client should expect the following responses from myCRMSIM when sending messages.
Successful Request (HTTP 200)
When the payload is valid and accepted, the API responds with:
Meaning:
- The event has been validated
- The message is queued successfully
- Delivery will be processed asynchronously
Invalid Request (HTTP 400)
Common causes:
- Missing location_id
- Missing or empty message_id
- Invalid channel value
- Invalid phone number format
Best Practices
- Always validate payloads before sending
- Treat HTTP 200 as accepted, not delivered
- Rely on STATUS-UPDATE events for final delivery state
- Implement retry logic only for non-200 responses
- Do not retry blindly on 400 errors
Summary Flow
- Send message → receive HTTP 200
- Wait for STATUS-UPDATE callbacks
- Process inbound MESSAGE events