Versions Compared

Old Version 6

changes.mady.by.user Julia Layne

Saved on

compared with

New Version Current

changes.mady.by.user Cody Crow

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

You can choose to receive notification events about your SMS messaging by registering webhooks. This is a step-by-step guide to registering a webhook to receive notification events when a message is sent, finalized, or received.

Panel
panelIconId1f48e
panelIcon:gem:
panelIconText💎
bgColor#ABF5D1

Update

You can now register webhooks through our web portal. In Volt Messaging, navigate to the Webhooks tab in your Account Settings to register new webhooks and update existing connections.


Note: during registration, an automated test request is sent to your webhook URL. Your server must return a successful response (2XX status code) to complete registration.

\uD83D\uDCD8 Instructions

...

  1. Set the Authorization header to the value Bearer <token>, replacing <token> with the API access token belonging to your organization.

  2. Construct a GraphQL query using the registerWebhook mutation:

    Code Block
    languagegraphql
    mutation registerWebhook ($url: String!) {
    registerWebhook (url: $url) {
        id
        url
        createdAt
        lastUpdatedAt
    }
}

  3. Construct a JSON object containing the GraphQL variables for the query created in the previous step:

    Code Block
    languagejson
    {
  "url": "https://example.com/webhooks"
}

  4. Send a POST request to https://api.respondflow.com/graphql with the GraphQL query and variables in the request body. We recommend using a GraphQL client library in the language of your choice to construct and send GraphQL API requests.

    For example, to send the above GraphQL request using curl:

    Code Block
    curl --location --request POST 'https://api.respondflow.com/graphql' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation registerWebhook ($url: String!) {\n    registerWebhook (url: $url) {\n        id\n        url\n        createdAt\n        lastUpdatedAt\n    }\n}","variables":{"url":"https://example.com/webhooks"}}'


    Once a webhook is registered, you should receive POST requests containing webhook notification event data related to your SMS messages.

Panel
panelIconIdatlassian-info
panelIcon:info:
bgColor#DEEBFF

Troubleshooting

Our server expects to receive a status code 200 from a successful POST request to the registered url, otherwise you will receive this error

Error from GraphQL API: webhook failed to respond successfully

🛠  Example webhook payloads

...

Code Block
languagejson
{
  "type": "messaging",
  "id": "rfw_6962ccb5_eb7654690ec04a0593cc645fd2353995",
  "payload": {
    "message_app_id": "40318006-1cae-4997-acbc-fe9a4aadb7dd",
    "id": "rf_o6aDxhawR227gt5wgZ2I",
    "to_number": "+15555550123",
    "from_number": "+15555550145",
    "valid_until": "2022-04-07T23:19:44.718+00:00",
    "type": "SMS",
    "text": "Sending a message to myself to demonstrate using the GraphQL API",
    "sent_at": "2022-04-07T22:19:44.985+00:00",
    "received_at": "2022-04-07T22:19:44.718+00:00",
    "provider_error_code": null,
    "provider_error_detail": null,
    "provider_error_title": null,
    "carrier_name": "T-MOBILE USA, INC.",
    "error_code": null,
    "status": "delivered",
    "parts": 1,
    "messaging_profile_id": "40017bf5-8809-4640-9925-da5c732667b7",
    "media": [],
    "encoding": "GSM-7",
    "direction": "outbound",
    "completed_at": "2022-04-07T22:19:46.119+00:00",
    "occurred_at": "2022-04-07T22:19:46.119+00:00",
    "event_type": "message.finalized"
  },
  "time": 1649369986
}

...

Code Block
languagejson
{
  "type": "messaging",
  "id": "rfw_6962ccb5_eb7654690ec04a0593cc645fd2353995",
  "payload": {
    "message_app_id": "40318006-1cae-4997-acbc-fe9a4aadb7dd",
    "id": "rf_o6aDxhawR227gt5wgZ2I",
    "to_number": "+15555550123",
    "from_number": "+15555550145",
    "valid_until": "2022-04-07T23:19:44.718+00:00",
    "type": "SMS",
    "text": "Sending a message to myself to demonstrate using the GraphQL API",
    "sent_at": "2022-04-07T22:19:44.985+00:00",
    "received_at": null,
    "provider_error_code": "40002",
    "provider_error_detail": "The message was flagged by a SPAM filter and was not delivered. This is a temporary condition.",
    "provider_error_title": "Blocked as spam - temporary",
    "carrier_name": "T-MOBILE USA, INC.",
    "error_code": "702",
    "status": "failed",
    "parts": 1,
    "messaging_profile_id": "40017bf5-8809-4640-9925-da5c732667b7",
    "media": [],
    "encoding": "GSM-7",
    "direction": "outbound",
    "completed_at": "2022-04-07T22:19:46.119+00:00",
    "occurred_at": "2022-04-07T22:19:46.119+00:00",
    "event_type": "message.finalized"
  },
  "time": 1649369986
}

...