Help Scout and Twilio integrate through the Help Scout Conversations API and Twilio's inbound webhook to bring SMS into the Help Scout inbox as conversations, so agents handle customer text messages alongside email threads without switching to a separate tool. This integration is popular with small to mid-size support teams that use Help Scout for email-based support and want to extend that same shared inbox experience to SMS without the complexity of a full contact center platform. The connection creates Help Scout conversations from inbound Twilio SMS, links them to the correct Help Scout customer record by phone number, and captures agent replies from Help Scout webhooks to dispatch back to the customer via Twilio.
What You Need Before You Start
Register a Help Scout OAuth 2.0 application from your Help Scout account under Your Profile, then OAuth Applications, clicking New Application, and noting the client ID and client secret used to obtain access tokens via the client credentials grant flow at POST https://api.helpscout.net/v2/oauth2/token with grant_type=client_credentials. Your Help Scout API v2 base URL is https://api.helpscout.net/v2/ and all requests require the Authorization header set to Bearer {accessToken} obtained from the token endpoint. From Twilio, collect your Account SID, Auth Token, and an SMS-capable phone number, and set that number's Messaging webhook URL in the Console to your middleware inbound handler. You need to identify your Help Scout Mailbox ID, which you find by calling GET https://api.helpscout.net/v2/mailboxes/ with your access token and noting the id field of the mailbox where SMS conversations should appear.
Step-by-Step Integration Guide
When an inbound SMS arrives, your middleware parses From, Body, and MessageSid from the Twilio POST, then searches Help Scout for an existing customer with that phone by calling GET https://api.helpscout.net/v2/customers/?phone={E164number} with your Bearer token to check the _embedded.customers array in the response. If no customer exists, create one by calling POST https://api.helpscout.net/v2/customers/ with a body containing phones as an array with one object containing value set to the E.164 From number and type set to mobile, and use the Location header from the 201 response to extract the new customer ID. Create a Help Scout conversation by calling POST https://api.helpscout.net/v2/conversations/ with a body containing type set to email (Help Scout's API uses email type for all channel conversations), subject set to SMS from {From number}, mailboxId set to your mailbox ID, customer.id set to the customer ID, threads as an array with one object containing type set to customer and text set to the SMS body, and status set to active. Subscribe to Help Scout conversation reply events by registering a webhook at POST https://api.helpscout.net/v2/webhooks/ with a body containing url set to your reply handler endpoint, events containing convo.reply, and secretKey set to a shared secret for HMAC signature verification, then in your reply handler extract the reply text and customer phone and call the Twilio Messages API to send the reply back as SMS.
Common Issues and How to Fix Them
Help Scout OAuth access tokens expire after 48 hours and all API calls return 401 Unauthorized once the token expires, interrupting the inbound SMS to conversation flow for any messages that arrive after expiry. Implement automatic token refresh in your middleware by storing the token issue time alongside the access token, checking before every API call whether the token is older than 47 hours, and refreshing it proactively using the same client credentials grant before making the API call. Help Scout does not natively support SMS channel classification, so conversations created from Twilio SMS appear in the inbox as email-type conversations, which can confuse agents who cannot tell whether to reply in Help Scout or by phone. Add a tag to every SMS-originated conversation at creation time by including tags as an array containing a string like sms-channel in the POST body, and create a Help Scout saved search filter for that tag so agents can view the SMS queue separately from the email queue. Help Scout webhooks for conversation replies fire for all reply types including notes, which would cause your middleware to send a customer-facing SMS for every internal note added by an agent. Filter the webhook payload by checking the thread.type field in the webhook body and only dispatching the Twilio SMS reply when thread.type equals reply and thread.createdBy.type equals user, skipping all note type threads.
How to Get More from This Integration
Build a Help Scout customer profile enrichment step that runs after creating a new customer from an inbound SMS and calls the Twilio Lookup API at GET https://lookups.twilio.com/v2/PhoneNumbers/{number}?Fields=caller_name,line_type_intelligence to retrieve the caller name and line type, then updates the Help Scout customer record with that name using PATCH https://api.helpscout.net/v2/customers/{customerId}/ to give agents more context before they respond. Create conversation threading for multi-message SMS exchanges by tracking the Help Scout conversation ID per phone number in your middleware database, and on subsequent inbound SMS from the same number add a new thread to the existing open conversation using POST https://api.helpscout.net/v2/conversations/{conversationId}/threads/ rather than always creating a new conversation, keeping the full SMS history in one Help Scout thread. Implement agent-initiated outbound SMS by adding a Help Scout sidebar App using the Help Scout Custom App Beacon that displays a Send SMS button on open conversations, which calls your middleware with the conversation ID and message text, retrieves the customer phone from the conversation's primary customer, and dispatches the Twilio SMS while logging the event as a note on the conversation. Add delivery status tracking by configuring the Twilio StatusCallback on each outbound SMS to post to your middleware, which then calls POST https://api.helpscout.net/v2/conversations/{conversationId}/threads/ with type set to note and text set to SMS status: delivered or SMS status: failed plus the MessageSid, giving agents delivery confirmation inline in the conversation.
Conclusion
Help Scout and Twilio together add SMS as a first-class support channel inside the shared inbox your team already depends on, without requiring separate SMS tools or splitting agent attention. Get in touch with Telphi Consulting to build this integration for your Help Scout mailbox.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.