General Integration Patterns
What is the recommended way to integrate my backend with Tuco?
What is the recommended way to integrate my backend with Tuco?
Recommended pattern:
- Your front-end:
- Talks only to your own backend.
- Never holds Tuco API keys.
- Your backend:
- Stores a workspace-scoped Tuco API key securely.
- Calls Tuco’s public APIs for:
- Lead creation/import.
- Message sending.
- Line listing.
- Exposes its own internal APIs to your applications.
- Webhooks:
- You configure Tuco to send message and other webhooks to your backend.
- Your backend processes them and updates your internal systems (CRMs, data warehouse, etc.).
Can I integrate Tuco directly into my CRM?
Can I integrate Tuco directly into my CRM?
Yes, and the HubSpot integration is a good reference architecture:
- A CRM-side app:
- Provides UI inside the CRM (cards, workflow actions, settings).
- A backend connector:
- Knows how to talk to the CRM API.
- Uses a Tuco API key to talk to Tuco.
- Using Tuco’s documented APIs.
- Never calling internal worker endpoints or databases directly.
Webhooks & Events
Which webhooks are essential for a robust integration?
Which webhooks are essential for a robust integration?
At a minimum:
- Message webhooks:
- Delivery and fallback events, as documented in
/api-reference/message-webhooks.
- Delivery and fallback events, as documented in
- Generic event webhooks (where configured):
lead.created,lead.updated,availability.checked, etc.
- Keep message statuses in sync.
- Update contact availability.
- Trigger follow-up actions in your own systems.
How do I ensure webhooks don't overload my system?
How do I ensure webhooks don't overload my system?
Strategies:
- Implement a light ingress layer:
- Validates and authenticates requests.
- Quickly enqueues them to your own internal queue.
- Responds to Tuco within a short timeout.
- Process webhook payloads asynchronously:
- Database writes and downstream calls happen in background workers.
- Use backpressure and rate limiting internally:
- Ensure a spike in events from Tuco does not overwhelm downstream dependencies.
HubSpot-Specific Questions
How is the HubSpot app linked to my Tuco workspace?
How is the HubSpot app linked to my Tuco workspace?
The HubSpot backend:
- Uses HubSpot OAuth to identify the HubSpot account.
- Asks the user to either:
- Authenticate with Tuco, or
- Provide a Tuco API key.
- Stores the mapping:
- HubSpot portal ↔ Tuco workspace ↔ Tuco API key.
- Workflow actions and cards know which Tuco workspace to talk to.
- All calls from the backend to Tuco use the stored API key.
What data flows from Tuco back into HubSpot?
What data flows from Tuco back into HubSpot?
Typical flows include:
- Timeline events:
- Outbound Tuco messages (content, channel, status).
- Replies from recipients as inbound events.
- Status updates:
- Flags or properties that indicate last contacted/last replied dates.
- Tuco → HubSpot backend via public webhooks and APIs.
- Backend → HubSpot via officially supported HubSpot APIs.