Access API

The inbound payload change for conversation-based pricing

Current inbound Sent message-event payload

{
  "app": "DemoAPI",
  "timestamp": 1585344475993,
  "version": 2,
  "type": "message-event",
  "payload": {
    "id": "gBEGkYaYVSEEAgnZxQ3JmKK6Wvg",
    "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
    "type": "sent",
    "destination": "918x98xx21x4",
    "payload": {
      "ts": 1585344475
    }
  }
}

Proposed Sent message-event payload post CBP implementation

{
  "app":"DemoAPI",
  "timestamp":1580546677791,
  "version":2,
  "type":"message-event",
  "payload":{
      "id":"59f8db90-c37e-4408-90ab-cc54ef8246ad",
      "gsId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
      "type":"sent",
      "destination":"91XX985XX10X",
      "payload":{
        "ts":1585344475
      },
"conversation":{
        "id":"532b57b5f6e63595ccd74c6010e5c5c7",
        "expiresAt":1518780636,
        "type": "FEP/UIC/BIC"
      },
      "pricing":{
        "policy": "CBP/NBP",
        "category": "FEP/UIC/BIC"
      }
  }
}

We understand that the billable parameter is important and hence we have introduced a new event that you will receive on your callback URL, known as billing-event. The billing-event is described at the bottom of this article.

Conversation object description

Pricing object description

New callback event: billing-event

{
  "app": "DemoAPI",
  "timestamp":1580546677791,
  "version":2,
  "type": "billing-event",
  "payload":{
     "deductions":{
       "type": "FEP/UIC/BIC/FTC",
       "model": "NBP/CBP",
       "source": "whatsapp",
       "billable": "true/false"
     },
     "references":{
       "id":"59f8db90c37e-4408-90ab-cc54ef8246ad",
       "gsId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
       "conversationId":"532b57b5f6e63595ccd74c6010e5c5c7",
       "destination":"91XX985XX10X"
      }
   }
}

Note: You will start receiving the 'billable' flag in the billing-event from the 1st of March.

Deductions object description

References object description

Note

Once the conversational pricing is in place, businesses will receive the new message-event payload, which has additional properties: conversation and pricing.
Only the DLR event: sent (This event indicates that WhatsApp’s server has received the message) will be the one where you will obtain these additional details on conversational pricing.
The order of these notifications in your app may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.

Unable to receive an inbound event for a PDF file sent by the user?

There are various reasons due to which inbound media messages can fail. In the case of PDF files, the usual reason for failure is thumbnail validation.

For an Inbound message consisting of a PDF file, Facebook will validate the thumbnail size of the PDF file. Thumbnail sizes of only up to 64kb are allowed. If the limit is exceeded, the inbound message will not be delivered to your WhatsApp Business API, as the pdf fails at the receiver side (business) due to thumbnail validation. Additionally, in such a case, no inbound event is received to explain the reason. Please make sure that the file sent by the user, complies with WhatsApp's requirement.

If you still face any issues, please reach out to us at [email protected].

How do I set a webhook/callback URL for my app?

Learn how you can set a webhook/callback URL for your app.

For instance, if we generate a URL on webhook.site and set that URL as the callback URL for our WhatsApp Access API app on Gupshup, we will receive the following event.

You can use such tools to understand what payload Gupshup sends to your callback URL that you need to accept and handle in your web service.

Once your web service is scripted and deployed - use tools like Postman to test it by sending a dummy payload similar to what you receive while trying with webhook.site URLs. If your web service meets all the criteria mentioned here, you will successfully set the callback URL in the WhatsApp app.

Please try this approach to resolve your issue. If the problem persists, you can reach out to us at [email protected].

How do I send a template message using the API?

You can send an approved template message using the send message API. Click here to refer API document.

Is there an API to check my account's wallet balance?

Yes, you can check and create alert mechanisms to keep a track of your account's wallet balance using an API. Refer API document here.

How do I block a spam user? Is there an API for blocking users for sending spam messages?

Once your App is Live, you can block a user from your App's settings page as shown in the below screenshots:

Just go to your App's Dashboard - Settings - View Opt-ins - Block and you can block your Opted-in user for your Live App.

Apart from the UI, you can also use the following API to block spam users.

curl --location --request PUT 'https://api.gupshup.io/sm/api/v1/app/block/{{App-Name}}' \
--header 'apikey: {{APIkey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'phone={{Phone number that is to be blocked. eg:919876543210}}' \
--data-urlencode 'block=true'

IDE Bot not visible in "Link your bot" section of Access API App

This is an intermittent issue, where your IDE bot type is changed to some undefined value which is not supported to link with your Access API App that you have created on our platform. Hence, the bot-app linkage issue.

Alternative Solution: Till the issue is fixed, as an immediate solution, you can use this workaround to resolve your issue:

Create a new bot on our platform of type IDE.
Copy-Paste all bot code(index.js, default.src, default.js, and any other dependent file you have created in the bot project folder) from old bot to new bot.
Deploy the bot on prod.
Go to your App settings page and link the new bot.

For more details on this issue, you can write to us at [email protected],

Can I switch my app's type from Customer Support tool to Access API and vice versa?

Yes, you can change your app's type from customer support tool to Access API and vice versa. Please write to [email protected] with your app's name.

Note: If you switch an app's type from Customer support tool to Access API, all of the data is lost and cannot be recovered.

Why do I get a "Media URL Not Whitelisted" error? How do I whitelist a media URL?

This error occurs when you send media files from a sandbox app. Sandbox apps are limited and can only send sample media messages given below. This restriction is due to security reasons. You can send your media messages when your app is Live.

Image
JPG:

PNG:

Sticker

File
PDF:

VIDEO

AUDIO

https://www.buildquickbots.com/whatsapp/media/sample/audio/sample01.mp3

We noticed v1 to v2 migration notification on your Website? Do we need to make any changes on our code? If so, where can we see the documentation of that?

The version change notification on the website is only applicable to apps of type Access API created on our platform before 28th January 2020. If you have created an app of type Access API before the said date your set callback URL is receiving incoming event/message payload with version 1. Version v1 payload content type is application/x-www-form-urlencoded; charset=utf-8
v1 Sample payload:

Version v2 content type is application/json; charset=utf-8This is a major change one has to make in their web-application.
For API documentation for v2 click here.

Can i send image/video/audio/document with caption?

Yes, you can send an image/video/audio/document with a caption.

Where can I find API documentation?

You can refer to the API documentation here.

How can I send images as an album?

An album will not be created if any of the following are met:

Images with captions
Unread divider - user sees some images, but not the rest
Message from user or other participants if group only
Date header - new day between deliveries.

Can I send location/contact message using Gupshup's API

Yes, you can send location or a contact message using the send message API.

Is the order of messages guaranteed?

No, the order in which the messages arrive to the end user is not guaranteed to be in the same order as they were sent.

How many messages per second can I send using the API?

You can send up to 20 messages/sec.

I am unable to get audio/video URL on my callback. I just get a random ID in the incoming payload

Use the below API to get the media payload:

curl -X GET \ https://api.gupshup.io/sm/api/wamedia/{WhatsApp-App-name}/{VoiceID} \ 
	-H 'apikey: {Gupshup-Account-APIkey}'

Can I send media by byte streams?

WhatsApp doesn't support sending media by byte streams.

Will I receive message status notification like - message read, sent, delivered, etc.?

Yes, you can set your webhook/callback URL to receive inbound events. Your message status events will be sent to your callback URL. You can also select which events you want to receive from settings in the app dashboard. Learn more about inbound events.

Can I send messages to international numbers?

Yes, you can send and receive messages to international numbers.

Can I format text messages?

Yes, you can format text messages using formatting symbols.

What kind of attachments can I send on WhatsApp?

You can send the following attachments apart from Text (English and Unicode characters) -

Link
Document
- text/csv
- text/comma-separated-values
- text/plain
- application/csv
- application/vnd.ms-excel
- application/pdf
Image
- image/png
- image/jpeg
- image/jpg
- image/gif
Audio
- audio/mpeg3
- audio/x-mpeg-3
Video
- video/mpeg
- video/quicktime
- video/mp4
- video/mpeg
- video/x-mpeg
Location
Contact card

Learn more about supported content-types for different types of messages.

How to receive incoming messages?

You can receive incoming messages for your WhatsApp Business API by setting your app's webhook/callback URL.

Can Gupshup's WhatsApp Business API services be integrated with other CRM's such as Zoho Desk?

We do not offer ready plugins but you can use our APIs to integrate with different CRM platforms.

What is an Access API app? How does it differ from the Customer support tool?

An app of type Access API lets you send automated messages using our send message API and receive users' messages on your webhook/callback URL that we receive for your WhatsApp Business API number. You can do so by integrating our APIs with your service or application.
On the other hand, the customer support tool provides you with a user interface that allows you to view and manually respond to user queries with the help of customer support agents.