Webhooks - Corsair

The WhatsApp plugin handles incoming webhooks. Point your provider’s subscription URL at your Corsair HTTP handler (see Overview for setup context and the exact URL shape).

New to Corsair? See webhooks and hooks.

Webhook map

messages
- received (messages.received)
- statusChanged (messages.statusChanged)

HTTP handler setup

app/api/webhook/route.ts

import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";

export async function POST(request: Request) {
    const headers = Object.fromEntries(request.headers);
    const body = await request.json();
    const result = await processWebhook(corsair, headers, body);
    return result.response;
}

Events

Messages

Received

messages.received Incoming WhatsApp messages from customers Payload

Name	Type	Required	Description
`businessAccountId`	`string`	Yes	—
`phoneNumberId`	`string`	Yes	—
`displayPhoneNumber`	`string`	Yes	—
`contacts`	`object[]`	Yes	—
`messages`	`object[]`	Yes	—

contacts full type

{
  wa_id: string,
  profile?: {
    name?: string
  }
}[]

messages full type

{
  id: string,
  from: string,
  timestamp: string,
  type: string,
  context?: {
    from?: string,
    id?: string,
    referred_product?: {
    }
  },
  text?: {
    body: string
  },
  image?: {
    caption?: string
  },
  audio?: {
  },
  document?: {
    caption?: string
  },
  video?: {
    caption?: string
  },
  sticker?: {
  },
  location?: {
  },
  contacts?: {
  }[],
  interactive?: {
    button_reply?: {
      title?: string
    },
    list_reply?: {
      title?: string
    }
  },
  button?: {
    text?: string
  },
  order?: {
  },
  referral?: {
  },
  errors?: {
  }[]
}[]

Response data full type

{
  businessAccountId: string,
  phoneNumberId: string,
  displayPhoneNumber: string,
  contacts: {
    wa_id: string,
    profile?: {
      name?: string
    }
  }[],
  messages: {
    id: string,
    from: string,
    timestamp: string,
    type: string,
    context?: {
      from?: string,
      id?: string,
      referred_product?: {
      }
    },
    text?: {
      body: string
    },
    image?: {
      caption?: string
    },
    audio?: {
    },
    document?: {
      caption?: string
    },
    video?: {
      caption?: string
    },
    sticker?: {
    },
    location?: {
    },
    contacts?: {
    }[],
    interactive?: {
      button_reply?: {
        title?: string
      },
      list_reply?: {
        title?: string
      }
    },
    button?: {
      text?: string
    },
    order?: {
    },
    referral?: {
    },
    errors?: {
    }[]
  }[]
}

webhookHooks example

whatsapp({
    webhookHooks: {
        messages: {
            received: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

Status Changed

messages.statusChanged WhatsApp sent, delivered, read, failed, deleted, or error updates Payload

Name	Type	Required	Description
`businessAccountId`	`string`	Yes	—
`phoneNumberId`	`string`	Yes	—
`displayPhoneNumber`	`string`	Yes	—
`statuses`	`object[]`	Yes	—
`errors`	`object[]`	Yes	—

statuses full type

{
  id: string,
  status: sent | delivered | read | failed | deleted,
  timestamp: string,
  recipient_id?: string,
  conversation?: {
  },
  pricing?: {
  },
  errors?: {
    code?: number,
    title?: string,
    message?: string,
    error_data?: {
      details?: string
    }
  }[]
}[]

errors full type

{
}[]

Response data full type

{
  businessAccountId: string,
  phoneNumberId: string,
  displayPhoneNumber: string,
  statuses: {
    id: string,
    status: sent | delivered | read | failed | deleted,
    timestamp: string,
    recipient_id?: string,
    conversation?: {
    },
    pricing?: {
    },
    errors?: {
      code?: number,
      title?: string,
      message?: string,
      error_data?: {
        details?: string
      }
    }[]
  }[],
  errors: {
  }[]
}

webhookHooks example

whatsapp({
    webhookHooks: {
        messages: {
            statusChanged: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​Webhook map

​HTTP handler setup

​Events

​Messages

​Received

​Status Changed

Webhook map

HTTP handler setup

Events

Messages

Received

Status Changed