How to set up custom actions for crisis routing widget

• A Chatref account with an active agent for your mental health practice website.
• Access to the agent’s Custom Actions panel in the dashboard.
• The website widget snippet installed on every page where visitors may need help (copy it from the Embed tab).
• The endpoint of your crisis-alert receiver – a webhook URL that posts to your on-call team’s communication tool, or an email address your team monitors in real time.

Custom actions let Chatref collect details inside the chat and call an external service when a visitor says something that matches your rules. For mental health services, this becomes a safety net: a person in crisis can trigger a direct handoff without having to find a phone number or navigate a phone tree.

1. Open Custom Actions
   From your Chatref dashboard, go to Agents, select the agent you use for your mental health practice, and open the Custom Actions tab.

2. Create a crisis routing action
   Click Add action and name it something clear like Crisis routing. This name is for your team only – visitors never see it.

3. Set the trigger words
   Under When a message contains, enter the phrases you want to catch. Include direct and indirect expressions of distress, for example:
   suicidal, hopeless, can’t go on, want to die, kill myself, self-harm, end it all
   Add the variations your own visitors use; you can refine the list later using conversation insights.

4. Collect the details your crisis team needs
   In the Collect details section, add fields that Chatref will prompt for.

   • First name (Required)
   • Phone number (Required – so the team can call back)
   • Brief note (Optional – a field the visitor can fill with any immediate context)
     Mark the fields you cannot afford to miss as required. For crisis routing, requiring name and phone number is standard so someone can follow up within seconds.

5. Connect the action to your alerting tool
   Choose Trigger an external URL.

   Webhook URL: enter the endpoint that receives the visitor’s details. This could be:

   • A service that relays the message into your team’s Slack or Microsoft Teams channel,
   • A HIPAA-compliant messaging gateway,
   • A voice/email API that pages the on-call counselor.

   If your team relies on email alerts, enter a mailto-style webhook address provided by your email delivery service.

   Payload: Chatref will send a POST with a JSON body containing the collected fields along with the original message and a conversation link. A typical payload looks like:

   {
     "action_name": "Crisis routing",
     "fields": {
       "First name": "Jane",
       "Phone number": "+1234567890",
       "Brief note": "I can’t stop shaking"
     },
     "message": "I feel like ending it all",
     "conversation_url": "https://app.chatref.ai/..."
   }
   

   Add any required authentication headers (API key, token) in the Headers section of the action configuration.

6. Write the visitor reassurance message
   Under Auto-reply after action, compose a short, calm message the visitor sees while help is on the way. Example:
   A crisis counselor will reach out now. If you are in immediate danger, please call your local emergency services.

7. Save and enable
   Toggle the action to Active and save. It will now run on every message that arrives through the widget for this agent.

• Test in the Playground
  Open the agent’s Playground tab and send a message containing one of your trigger phrases. The agent should respond with the fields you defined, then show the reassurance message. The action’s result appears in the conversation log as a tool execution.

• Watch the action log
  Under the agent’s activity or in the custom action log, confirm the webhook fired and returned a success status (e.g., HTTP 200). A failure will show the response code and any error body.

• End-to-end verification with your team
  Send a test message using a real crisis phrase, filling in the fields as a visitor would. Ask your on-call team to confirm they received the alert on their side. Run this test at least once during setup and monthly thereafter – notification paths degrade silently if not exercised.

• Debugging
  If the webhook fails, check:

  • The endpoint URL is reachable and accepts POST,
  • Headers are correct (API key or token not expired),
  • Your network accepts incoming connections from Chatref’s IP ranges (if whitelisting is required, consult Chatref support for the current list).

Crisis phrase not catching
Visitors use language you didn’t anticipate. Expand the trigger list to include idioms and misspellings. Review the Insights weekly to see the phrases that came through without firing the action, then add them.

Webhook endpoint down or rejecting payload
If the receiving service is down, Chatref marks the action as failed but won’t retry automatically. Build resilience by creating a second custom action – a fallback – that sends an email alert instead. Chain them: condition “previous action failed” → “send email.”

Fields not showing or visitors skipping them
If you mark a field as optional, some visitors will omit it. For crisis routing, keep the phone number required. Also test that the prompt flow doesn’t interrupt the visitor’s sense of urgency; asking for a name first, then a phone is less jarring than one long form.

Widget absent on critical pages
The crisis routing action only works where the Chatref widget is embedded. Place the snippet on every high-traffic page – homepage, appointment booking, contact page – and behind any patient portal login. Use origin allowlisting to prevent unauthorized embeds and false alerts.

Language mismatch
If your practice serves multilingual visitors, add trigger words in those languages as well, or use separate agents per language if the phrasing differs significantly.

HIPAA and data handling
Chatref processes data grounded in your content, but it’s your responsibility to ensure the fields you collect and the transmission path meet your compliance obligations. Minimize collected data to what’s operationally necessary, and avoid storing full crisis conversation transcripts beyond your retention policy.

What causes crisis routing widget problems for Mental Health Services?

The most common cause is incomplete trigger word lists that miss how people express distress – visitors use slang, misspellings, or indirect phrases. Other frequent issues: the receiving webhook endpoint being unavailable or misconfigured, the widget not being present on the page where the visitor lands during a crisis, and teams forgetting to test the full flow after making changes to the alerting tool.

How do I improve crisis routing widget for Mental Health Services?

Add redundancy: set up a primary webhook alert and a fallback email action that triggers if the first fails. Review Chatref’s conversation insights weekly to catch new crisis phrasing and add it to the trigger set. Keep the widget highly visible – use a persistent chat bubble with a label like “Crisis help” – so it’s there the moment someone needs it. Finally, run a live test every month with your on-call team to keep the path reliable.