Conversation Events Guide

Overview

Webhooks allow your application to receive automatic notifications when specific events occur in your Popp AI conversations. Each webhook event includes information about what happened and relevant conversation data.

Event Structure

Every webhook event follows this structure:

{
  "event": "string",
  "data": {
    "recordId": "string",
    "organizationId": "string",
    "conversationStatus": "COMPLETED_SCREENING_FAILED" | "COMPLETED_SCREENING_PASSED",
    "scorecardTotalValue": number | null,
    "externalId": string | null,
    "participantLastName": string | null,
    "participantFirsName": string | null,
    "externalCampaignId": string | null,
    "screeningQuestionsOutcome": [
      {
        "questionOutcome": "PASSED" | "FAILED",
        "screeningQuestion": "string",
        "responseSummary": "string"
      }
    ]
  }
}

Where:

• event: Identifies the type of event that occurred
• data.recordId: Unique identifier for the specific conversation
• data.organizationId: Your organization's unique identifier

Available Events

1. Conversation Started

Event Name: CONVERSATION_STARTED

Triggered when a new conversation begins with a candidate. This event fires when the initial message is successfully sent to the candidate.

2. Conversation Completed

Event Name: CONVERSATION_COMPLETED

Triggered when a conversation with a candidate reaches its conclusion. After receiving this event, you can use the Get Conversation endpoint to retrieve detailed information about the conversation outcome.

The conversation can have different statuses:

• COMPLETED_SCREENING_PASSED: Candidate has passed the screening
• COMPLETED_SCREENING_FAILED: Candidate has not met the screening criteria
• CLOSED: Conversation was closed for other reasons

For conversations with status COMPLETED_SCREENING_PASSED or COMPLETED_SCREENING_FAILED, you can access the screening results in the screeningQuestionsOutcome field of the conversation response.

3. Conversation Needs Review

Event Name: CONVERSATION_NEEDS_REVIEW

Triggered when the Popp conversation engine identifies that human intervention is needed. Common scenarios include:

• The candidate asks a question that the AI cannot confidently answer
• Complex situations requiring human judgment
• Unusual or unexpected responses that need verification

Implementation Example

Here's a basic example of how to handle these webhook events:

app.post('/webhooks/popp', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'CONVERSATION_STARTED':
      // Handle new conversation
      console.log(`New conversation started: ${data.recordId}`);
      break;

    case 'CONVERSATION_COMPLETED':
      // Fetch conversation details
      const conversation = await poppApi.getConversation(data.recordId);
      // Process completion status
      handleCompletedConversation(conversation);
      break;

    case 'CONVERSATION_NEEDS_REVIEW':
      // Alert relevant team members
      notifyReviewTeam(data.recordId);
      break;
  }

  res.status(200).send('Webhook received');
});

Best Practices

1. Acknowledge Quickly

   • Return a 200 status code as soon as you receive the webhook
   • Process the event asynchronously if needed

2. Handle Retries

   • Implement idempotency checks using the recordId

3. Monitoring

   • Log webhook events for debugging
   • Set up alerts for failed webhook processing
   • Monitor webhook latency

Troubleshooting

Common issues and solutions:

1. Missing Events

   • Verify your webhook endpoint is accessible
   • Check your webhook logs for failed deliveries
   • Ensure your endpoint consistently returns 200 status codes

2. Processing Errors

   • Log the full event data for debugging
   • Implement error handling for the getConversation API calls
   • Set up monitoring for webhook processing failures

Need Help?

If you encounter any issues or need additional assistance:

1. Review your webhook logs
2. Check your API credentials
3. Contact Popp AI support with specific event details

Remember to include your organizationId and relevant recordId values when seeking support.