Instagram DM integration: connecting, the inbox and removing

When the Instagram DM integration is connected, direct messages sent to your Instagram business account land in the shared Piyzi inbox and your whole team replies from one place. Comments on your posts are a separate Pi Store card — connecting DMs does not bring comments along.

Prerequisites

• A Piyzi account with an active subscription.

• Being the business owner, or having the “Entegrasyonları yapabilir” (manage integrations) permission in your role. The “Entegrasyonları görebilir” (view integrations) permission is enough to open Pi Store, but without “Entegrasyonları yapabilir” clicking a card opens nothing.

• Your Instagram account must be a business (professional) account. Personal accounts cannot be connected.

• You must sign in as an admin of that Instagram account during authorization.

• A Facebook Page is not required. Piyzi uses Instagram Login, so studios and salons with no Facebook Page can still connect.

Connecting the integration

1. In the left menu, open My Business → Pi Store.

2. Under the Messaging heading, click the Instagram DM card; the “Instagram DM Connection” dialog opens.

3. Click “Connect with Instagram”. A pop-up window opens.

4. Sign in to Instagram in that window and approve the requested permissions.

5. When the pop-up closes, the page reloads by itself: the card badge shows “Connected” and a Messaging → Inbox entry appears in the left menu. When you open the card again, the dialog shows “Instagram Connected” together with the connected @username.

The same Instagram account can be connected to more than one Piyzi business (for example two branches). If the account is already connected to another Piyzi business, you will see a confirmation question during connection; if you approve, incoming messages appear in the inbox of every connected business separately and each business can reply on its own side. If you decline, the connection is not established.

Requested permissions

• instagram_business_basic: reads your account's basic information (username, name, profile picture) so the connection can be matched to the right business, and fetches the sender's username, name and profile picture once so the inbox does not show a raw numeric ID.

• instagram_business_manage_messages: receives incoming direct messages, sends your replies, marks conversations as read and sends reactions.

Your followers, your posts, your ad accounts and your comments are not accessed with these permissions. Comments require the separate Instagram Comments card and its own permission.

Using the inbox

After connecting, a Messaging → Inbox entry appears in the left menu for staff whose role has the “WhatsApp mesajlarını görebilir” (view messages) permission; replying needs “WhatsApp mesajı gönderebilir” (send messages). Although their names mention WhatsApp, these permissions cover Instagram DM too. Among the built-in roles only Yönetici (Manager) has them. The inbox is shared: WhatsApp and Instagram conversations sit in the same list, and if more than one channel is connected the tabs above the list (All / WhatsApp / Instagram DM) filter it.

Replying to messages

• You cannot start an Instagram conversation. Instagram's rules mean a conversation only exists once the customer messages you; the “Start Chat” button in the inbox is for WhatsApp only.

• The customer's message opens a 24-hour reply window. Within that window you can reply freely; the remaining time is shown under the composer.

• Use the paper clip to send photos, videos and audio; documents cannot be sent over Instagram DM.

• Hover over a message to reply to it or react to it. Instagram accepts a limited set of reactions, so the emoji you pick is mapped to the closest supported one.

• When you open an unread conversation, it is marked as read on Instagram as well and the customer sees “seen”. An information strip above the conversation list reminds you of this once.

• Replying requires the send permission; viewing the inbox only requires the view permission.

Incoming attachments and shares

• Photos, videos and audio are downloaded to Piyzi and shown directly in the bubble.

• A shared post or Reel is labelled “Shared content (Reel/post)”. For a post the thumbnail is downloaded and shown; a Reel arrives as an Instagram link, so the bubble offers to open it on Instagram instead of showing a preview.

• A reply to your story is labelled “Reply to a story”, and being mentioned in a story is labelled “Mention in a story”.

• A file sent by the customer is shown as a document and can be opened — you just cannot send one back.

• Anything Instagram delivers in a form Piyzi cannot render is shown as “Unsupported message type”, so no message is silently lost.

Assigning and closing a conversation

• The Conversation Management panel on the right is internal only: the customer is never notified of anything you do there.

• Select a staff member under “Staff member handling the conversation”. The thread then shows “{name} joined the conversation”.

• Removing the assignment writes “{name} left the conversation”; handing it to someone else writes both events in order.

• Only staff with an active membership in this business can be assigned.

• “Close Conversation” asks for confirmation, closes it and writes “The conversation was closed by …”. If the same person messages again it opens as a separate conversation — the customer never notices.

• Assignment and closing both require the send permission.

Customer matching and the profile picture

• Instagram conversations are matched to a customer by the Instagram username on the customer card. Case and a leading @ do not matter.

• The webhook only carries an account ID, not the username, so Piyzi fetches the profile once and then matches. That is why the very first message may briefly show a numeric ID.

• While a conversation is unmatched, matching is retried on every incoming message — so adding the customer later fixes the older conversation as well.

• “Match with an existing customer” also writes the Instagram username onto the customer card (unless the card already has one or another customer uses it), so later conversations match by themselves.

• “Add as a new customer” writes to your customer database and therefore requires the “Müşteri oluşturabilir” (create customers) permission.

• The profile picture comes from Instagram's CDN and that link expires over time. When it does, the picture stops loading and the initial letter is shown instead — nothing is broken. If the customer card has a photo, that photo is used first.

Notification settings

• The gear-icon Notification Settings button above the conversation list opens the panel; both viewing and changing it require the “Mesajlaşma bildirim ayarlarını yönetebilir” (manage messaging notification settings) permission.

• For every staff member you can toggle WhatsApp, IG Message, IG Comment and Google Review separately; clicking a person's name toggles all four.

• If a conversation is assigned, the notification goes only to the assignee — even if they are not on the list.

• If nothing has been configured yet, only the business owner is notified. If the list exists but is empty, nobody is notified.

• At most one notification is sent per conversation every 2 minutes, and notifications only reach staff who are signed in to the mobile app and have not turned on Do Not Disturb in their own account (My Account → Notifications).

Deleting a conversation

• “Delete Conversation” is a separate permission from closing (“Sohbet silebilir (yalnız Piyzi tarafından)” on the role screen), because it is permanent and audit-logged. The business owner and the built-in Yönetici (Manager) role have it.

• The conversation and all of its messages are removed from Piyzi, on every Piyzi device, and this cannot be undone.

• It is deleted on Piyzi's side only. Meta's APIs do not allow deleting the copy in the other person's Instagram app — there is no such option, for anyone.

• If the same person writes again, a clean new conversation opens; the old history does not come back.

Removing the app

1. Open My Business → Pi Store.

2. Click the Instagram DM card.

3. Click “Disconnect”. There is no confirmation: the connection is removed straight away and the page reloads.

• New messages are no longer received and you can no longer send.

• Conversations and messages already in Piyzi stay readable — the integration is deactivated, not erased.

• The Inbox entry disappears from the menu when no messaging channel is left connected.

• Instagram Comments is a separate card: disconnecting DMs from Pi Store does not disconnect comments.

• You can reconnect at any time by following the same steps.

You can also remove the app on Instagram's side, from your account's app settings. Instagram then notifies Piyzi and both the Instagram DM and the Instagram Comments connections of that account are deactivated automatically. If you additionally submit a data deletion request to Meta, every Instagram conversation and comment belonging to that account is removed from Piyzi.

Troubleshooting

• The card does not show “Connected”: a pop-up blocker may have interrupted the authorization, or you may have closed the Instagram window before it finished. Try again from Pi Store.

• Authorization fails: make sure the account is a business (professional) account and that you are signing in as an admin of it.

• There is no Inbox in the menu: the integration may be disconnected, or your role may be missing the “WhatsApp mesajlarını görebilir” permission.

• “Your Instagram DM connection has expired — reconnect via Pi-Store to send messages”: the Instagram token is refreshed automatically, but a password change or a revoked permission invalidates it. Incoming messages keep arriving; to send again, open the Instagram DM card in Pi Store, click “Disconnect” and then “Connect with Instagram”.

• You cannot send a reply: the 24-hour window has probably closed. On Instagram there is no template fallback — you can send again once the customer writes to you.

• The Conversation Management panel is missing: the browser window is narrower than 1400 pixels; zoom out or use the mobile app.

• A conversation shows a number instead of a name: the profile could not be fetched (a private profile, or a temporary Instagram error). The conversation still works; match it to a customer manually.

• The profile picture does not load: the Instagram CDN link has expired. The initial letter is shown instead and no action is needed.

• The customer is not matched: fill in the Instagram username on the customer card, or use “Match with an existing customer” — the username is then saved for next time.